| Previous | Next |
| DB_E_BADLOCKMODE | DB_E_BADCOLUMNID |
DB_E_PARAMNOTOPTIONAL
No value given for one or more required parameters
Exact value and interpretation
DB_E_PARAMNOTOPTIONAL has the unsigned 32-bit value 2147749392 (0x80040E10) and the signed representation -2147217904. AllStat defines the result as “No value given for one or more required parameters”. In the concrete failure represented here, ICommand::Execute is called without a value for one or more required parameters.
The high bit is set for DB_E_PARAMNOTOPTIONAL, so it is a failure HRESULT rather than a success or informational status. Its facility field is 4 (FACILITY_ITF) and its low code is 3600 (0x0E10). Those bit fields place DB_E_PARAMNOTOPTIONAL in an interface-defined family, but they do not reveal the provider, object identity, method, rowset generation or command state that produced it.
OLE DB contract boundary
DB_E_PARAMNOTOPTIONAL must be interpreted against this contract: OLE DB command parameters are described through ordinals, names, provider types and a parameter accessor; the command definition and parameter metadata must agree with the DBPARAMS buffer supplied to ICommand::Execute.
Start with the command object, parameter metadata and parameter accessor used for the execution when investigating DB_E_PARAMNOTOPTIONAL. Preserve DB_E_PARAMNOTOPTIONAL before ADO, ATL, .NET, a database abstraction layer or an application exception replaces it with a generic message; the exact interface and method matter because one OLE DB object can expose several contracts with different preconditions.
Evidence to collect before changing the system
A useful DB_E_PARAMNOTOPTIONAL record includes provider CLSID and version, process architecture, interface and method, COM apartment and thread, object correlation ID, transaction state, and the first preceding HRESULT. When DB_E_PARAMNOTOPTIONAL involves parameter names, parameter values, procedure names and command text, record types, lengths, hashes or redacted identifiers instead of secrets or full business data.
- Evidence 1 for
DB_E_PARAMNOTOPTIONAL: the command's parameter count, names and ordinals. - Evidence 2 for
DB_E_PARAMNOTOPTIONAL: the parameter accessor bindings and DBPARAMS count. - Evidence 3 for
DB_E_PARAMNOTOPTIONAL: GetParameterInfo or SetParameterInfo metadata for optionality and type.
Specific conditions that produce this result
- Cause 1 for
DB_E_PARAMNOTOPTIONAL: the parameter accessor omits a required ordinal. - Cause 2 for
DB_E_PARAMNOTOPTIONAL: a required binding reports DBSTATUS_S_ISNULL when NULL is not accepted. - Cause 3 for
DB_E_PARAMNOTOPTIONAL: metadata changed but the consumer still binds the previous parameter set.
Diagnostic sequence
- Capture
DB_E_PARAMNOTOPTIONALimmediately at the native OLE DB return and obtain the current OLE DB error object before another COM call replaces thread error information. - Identify the exact stage for
DB_E_PARAMNOTOPTIONAL: ICommand::Execute is called without a value for one or more required parameters. - For
DB_E_PARAMNOTOPTIONAL, compare the live command, rowset, accessor or schema state with the metadata and properties actually granted by the provider. - For
DB_E_PARAMNOTOPTIONAL, inspect per-binding, per-property, per-row or per-record statuses whenever the method supplies them; the aggregate result may not identify the rejected element. - For
DB_E_PARAMNOTOPTIONAL, reproduce the issue with the smallest command, rowset or definition operation that preserves the same contract boundary. - For
DB_E_PARAMNOTOPTIONAL, apply one evidence-backed correction, then verify that the operation succeeds and does not merely change into a nearby HRESULT.
Retry and recovery policy
Retry rule for DB_E_PARAMNOTOPTIONAL: retry after supplying all required parameter values through a valid parameter accessor. A safe DB_E_PARAMNOTOPTIONAL retry must use a changed input, object generation, provider capability or state transition. If the call returning DB_E_PARAMNOTOPTIONAL could have created, updated, deleted or copied data, determine partial completion before replaying it.
For DB_E_PARAMNOTOPTIONAL, use bounded retries and preserve cancellation. For DB_E_PARAMNOTOPTIONAL, configuration and contract failures should normally fail fast; concurrency, resource or transient state failures may justify retry only after their stated precondition changes.
Corrective actions
- Action 1 for
DB_E_PARAMNOTOPTIONAL: bind every required parameter by its correct ordinal. - Action 2 for
DB_E_PARAMNOTOPTIONAL: distinguish missing parameters from explicit NULL values. - Action 3 for
DB_E_PARAMNOTOPTIONAL: refresh parameter metadata after procedure or command definition changes.
Practical incident
A stored procedure gains a required input parameter but an older client sends its previous accessor; refreshing parameter metadata resolves DB_E_PARAMNOTOPTIONAL. The diagnostic value comes from retaining DB_E_PARAMNOTOPTIONAL together with the failing interface and object state, not from reducing every provider result to “database error”.
Implementation guidance
Code handling DB_E_PARAMNOTOPTIONAL should release OLE DB resources in ownership order, preserve every provider error record, and log granted properties rather than only requested properties. When handling DB_E_PARAMNOTOPTIONAL, handles such as HACCESSOR, HROW, HCHAPTER and provider-specific region tokens must never be treated as portable integers across object lifetimes.
When DB_E_PARAMNOTOPTIONAL crosses an abstraction boundary, attach a stable correlation ID and structured fields for the native HRESULT, provider source, interface IID, method, object generation and operation phase. For DB_E_PARAMNOTOPTIONAL, do not log passwords, access tokens, complete SQL text or unrestricted row values merely to make the event easier to search.
Difference from related HRESULT values
DB_E_BADPARAMETERNAME rejects an unrecognized name, while DB_E_PARAMNOTOPTIONAL reports that a required parameter value was not provided. Keep these outcomes separate in telemetry and user-facing remediation because DB_E_PARAMNOTOPTIONAL requires a different next action.
Official Microsoft references
- Microsoft: ICommandWithParameters — official documentation relevant to
DB_E_PARAMNOTOPTIONAL. - Microsoft: using OLE DB parameters — official documentation relevant to
DB_E_PARAMNOTOPTIONAL. - Microsoft: ICommand — official documentation relevant to
DB_E_PARAMNOTOPTIONAL.
Looking for a different code? Search another status or error code.