One of my favorite error codes: Optional parameter missing

The error Optional parameter missing sounds awfully paradoxical, doesn't it. I mean, if the parameter is optional, why are you complaining that it's missing?

This KB article explains why, specifically, the part that says, "If a parameter is omitted, the calling program must…".

For those who don't want to click through, here's the deal: Methods described in a type library can declare parameters as optional. Optional parameters must come at the end of the parameter list, of course. The catch is how you programmatically invoke a method that contains optional parameters.

If you want to call a method that has optional parameters, you still have to pass the parameters. But you have to pass them a special way so that the method knows that they were omitted. (Specifically, you have to pass them as type VT_ERROR, code DISP_E_PARAM­NOT­FOUND.)

In other words, an optional parameter is optional from the high-level language, but it isn't optional at the low-level interface. Rather the optional keyword instructs the scripting engine to deploy syntactic sugar and allow the script to omit the parameters. The scripting engine then must follow specific rules in providing values for the parameters that were omitted by the script author.

In the lingo of C# and C++, a parameter declared optional in the TLB is really a mandatory parameter whose default value is DISP_E_PARAM­NOT­FOUND.

Comments (25)
  1. Joshua says:

    Given C's definition of optional (DLL linking always follows C rules), this no longer seems insane.

    [IDispatch is an interface for scripting languages (VB, JavaScript), not C. From a scripting standpoint, what would you call a parameter that you don't need to pass? -Raymond]
  2. Kirillenseer says:

    So the Name "optional" is actually a lie. Good to know.

    [It is optional from the standpoint of the scripting language (VB, JavaScript). You can pass one parameter or you can pass two. The second parameter is optional. If you omit the second parameter, the scripting engine will fill it in for you. If you want to apply C++ terminology to it, the equivalent term is "default" except that you don't get to choose the default value. -Raymond]
  3. Zarat says:

    I'd say it more comes down to inexact terminology. It's the value thats optional, not the parameter.

  4. pc says:

    While it's definitely an amusing error message, I still think it gets beat by "Keyboard not found, press F1 to contunue" and the like.

  5. Simon says:

    @pc – yes the 'F1 to continue' at first glance does look funny. But it describes exactly how to continue: plug in a keyboard so you can press F1 and then press F1. And TA DAA! it works too!

  6. dave says:

    This comment intentionally left blank.

  7. Eric says:


    Personally my favorite is the error message "Warning: Monitor not found" displayed during the boot of my HTPC, since how are you seeing it without a display connected?

  8. j b says:

    I laughed at the "Keyboard not found, press F1 to continue message" until the day I bought new tires for my car: The tires were mounted on the rims, and in a greasy, dirty garage (the way garages are) mounted on this apparatus to balance them by adding small weights – I guess most of you have seen how they do it. The guy switched on the PC controlling the machine, it came up with this message and a huge green square marked "F1", and the guy hit it with his fist. The screen was pressure sensitive, and every subsequent operation was controlled by hitting large control fields on the screen. There was no keyboard, just this screen – which was enclosed in a sealed "bag" of strong, transparent plastic. In that environment, a traditional keyboard wouldn't survive for more than a week or two.

    Today, people ought to be so familiar with touch displays that this shouldn't surprise them at all. Twenty years ago, when I first saw this, it was not at all common. Since then, I have repeatedly used this story to explain to people why the error message is NOT ridiculous, but fact is that even today, nine out of ten are just as amused as people were twenty years, insisting that "Well, but that is a veeery special case…". I don't think it is.

  9. viila says:


    The problem with that is that the AT/PS2 interface is /not/ hot-plug, so it's encouraging you to do something you shouldn't. Of course, today with USB keyboards it's reasonable, but the message was around long before they were the norm, or even existed.

    (There are of course other reasonable scenarios, such as the touchscreen mentioned by j b. Or maybe the keyboard was undetected for some reason, but exists and can emit F1 to the bus. Or the keyboard is behind a KVM which is currently switched to control another PC. Etc…)


    Well, you've managed to see that message somehow, haven't you? :P

  10. Miff says:

    AFIK C# doesn't have optional parameters per say. You can create a parameter with a default value (to call it programatically, pass that default value), or you can overload a method with a different signature that doesn't include the parameter (in which case, you have to pass different parameters to Type.GetMethod.

  11. Rob says:

    @Miff: C# does have optional parameters.  The language spec defines them as such.  However, the parameters are only optional at the call site; the callee doesn't fill in default values.  Optional parameters as specified by the C# language require the default value to be specified in metadata so that the compiler can add them in at compile time.

  12. Nacimota says:

    I remember learning something like this several years ago when I was playing around with C#. A lot of COM APIs (like Office) use optional parameters all over the place, but since C# had no support for optional parameters at the time you still had to specify them. You ended up writing something like:

    Document.SaveAs(ref filePath, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing, ref missing)

  13. Evan says:

    I agree with Zarat, though maybe I'm coming from a C/C++ background. C doesn't have any sense of optional parameters*, but a lot of C APIs still have "optional" parameters. For instance, if you have a function that takes an output parameter, maybe not all callers will be interested in the output value, so it makes sense to allow the parameter to be NULL. It's the difference between:

     void random1(int * out_val) { *val = 9; }

     void random2(int * out_val) { if(val) *val = 9; }

    (Obviously this is a contrived example because (1) why not just return it via an actual return and (2) why would you call it if you weren't interested in the result.) And in the case of 'random2', I think it's quite reasonable to describe the 'out_val' parameter as being "optional".

    * Technically you can sort of hack it with … a la the 'open' syscall in POSIX, but let's not go there.

  14. Sours says:

    My favorite error messages were from The Elder Scrolls: Daggerfall.  

    The first went something like: If you see this error contact John.

    The second: The tree that was previously deleted has now been deleted.

    Any idea on how to grab those from the exe?

  15. Henke37 says:

    @Sours: Just run strings on the executable.

  16. Neil says:

    @viila: I've not come across a computer that doesn't recognise a keyboard plugged in after it was switched on. Mice on the other hand cause me more trouble, although occasionally unplugging and reconnecting the keyboard will also reset the mouse.

  17. foo says:

    By far my favourite error code is ERROR_SUCCESS. I love it when functions return that one.

  18. Rick C says:

    Neil, modern computers with PS/2 ports will generally be able to stand hot-plugging, but I think that's not in the original spec. I've seen older computers that would lock up if you plugged in a keyboard after powerup.  I'm pretty sure the pre-PS/2 design, the old 5-pin DIN plugs, would freeze up in those circumstances too (but it's probably been 15 years since I've seen one of those).

  19. Rick C says:

    IIRC ERROR_SUCCESS usually means that the program missed checking for an error when it should have, and a subsequent operation cleared the error status.

  20. It's like failing an optional university class. It is optional to take the class but when you took it, failing to participate in final exam or failing to achieve adequate grades means failing the optional class.

  21. Yuri says:

    I'm always slightly amused when I see a compilation error of the sort:

    Cannot implicitly convert type 'X' to 'X'

  22. foo says:

    @Rick C – You might be thinking of a case where someone does something like the following:

    auto ret = ReadFile(lets just say the file handle is valid); … CloseHandle(valid handle); if (!ret) ReportError("Failed to read file because",,,,GetLastError());

    In this case the successful CloseHandle call will reset the last error to zero (success), so the reason for the read failure is gone. But some API's will still just return success if the call works (see the Registry functions for example).

    Fix is just use: auto ret = ReadFile(yadda); if(ERROR_SUCESS == ret) {yay!} else {error} <– (joking)

  23. Azarien says:

    @Rick C: I have hot-plugged the old DIN keyboard many times and it did not explode. Maybe it was not old enough :-)

  24. viila says:

    Hot-plugging PS/2 or DIN is not a guaranteed failure, or even necessarily a problem. But in the worst case, you could actually destroy your keyboard controller since the spec was designed for the I/O pins to be directly connected to the plug without any protection or buffering. The older the hardware, the more likely this is. On hardware made since at least around 2000s it's highly unlikely, because people are people and manufacturers aren't stupid, but it's still a theoretical possibility for a 100% in-spec controller to die from hot-plugging because it lacks safeguards.

    And yes, I have also hot-plug PS/2 keyboards for various reasons without incident, including to get past the F1 prompt (because waiting 10 seconds for the computer to re-POST and re-memcheck is such a drag, I just wanna get computing NOW! :P)…

  25. jas88 says:

    I'm reminded of my last passport application form, where apparently some automated processing had been introduced – so the various non-applicable options had to be left absolutely scrupulously blank or the application would be rejected: no "N/A", not even a tiny mark. No corrections of any kind allowed, either, and all in pen. With several pages of rather opaque language along the lines of "Place of birth? If born after Nov 1 1983, or between Jan 1 1972 and Oct 31 1983, or born outside the UK before those dates except while one or more parent(s) were employed in government service …" – all sorts of odd rules depending on parents' nationality, marital status at the time, date…

    I remember dire warnings about hot-plugging non-USB keyboards – I had a feeling some of the early improvements on that weren't big improvements, either (instead of the power surge blowing the keyboard controller chip, it would blow the fuse on the keyboard connection … still leaving a dead keyboard port!). I tended to treat the "F1 error" as a safe point to power off and re-check the connection, rather than to try hot-plugging and carry on booting. Thinking back, though, a loose connection must have been equivalent to hot-plugging, so if that did cause damage it would have been much more common than I can recall.

Comments are closed.