What does HRESULT 0x80040E4A (DB_E_NOTPREPARED) mean?

 
Previous Next
DB_E_NULLACCESSORNOTSUPPORTED DB_E_BADACCESSORTYPE

DB_E_NOTPREPARED

Command was not prepared

Exact value and interpretation

DB_E_NOTPREPARED has the unsigned 32-bit value 2147749450 (0x80040E4A) and the signed representation -2147217846. AllStat defines the result as “Command was not prepared”. In the concrete failure represented here, a method requiring a prepared command is called after command text was set but before successful ICommandPrepare::Prepare.

The high bit is set for DB_E_NOTPREPARED, 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 3658 (0x0E4A). Those bit fields place DB_E_NOTPREPARED in an interface-defined family, but they do not reveal the provider, object identity, method, rowset generation or command state that produced it.

Evidence to collect before changing the system

A useful DB_E_NOTPREPARED 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_NOTPREPARED involves command text, parameter values, object names and query-plan details, record types, lengths, hashes or redacted identifiers instead of secrets or full business data.

  • Evidence 1 for DB_E_NOTPREPARED: the command-state transition history.
  • Evidence 2 for DB_E_NOTPREPARED: the Prepare HRESULT and OLE DB error records.
  • Evidence 3 for DB_E_NOTPREPARED: changes to command text, parameters or properties after preparation.

OLE DB contract boundary

DB_E_NOTPREPARED must be interpreted against this contract: an OLE DB command moves through explicit states: command definition, properties and parameters are established before optional preparation and execution; dialect, query-tree and optimizer contracts are provider-specific and should be inferred only from reported capabilities.

Start with the active command object, its state transition history, dialect and provider error records when investigating DB_E_NOTPREPARED. Preserve DB_E_NOTPREPARED 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.

Specific conditions that produce this result

  • Cause 1 for DB_E_NOTPREPARED: Prepare was never called.
  • Cause 2 for DB_E_NOTPREPARED: Prepare failed but the consumer continued.
  • Cause 3 for DB_E_NOTPREPARED: command text or relevant properties changed and invalidated the prepared state.

Diagnostic sequence

  1. Capture DB_E_NOTPREPARED immediately at the native OLE DB return and obtain the current OLE DB error object before another COM call replaces thread error information.
  2. Identify the exact stage for DB_E_NOTPREPARED: a method requiring a prepared command is called after command text was set but before successful ICommandPrepare::Prepare.
  3. For DB_E_NOTPREPARED, compare the live command, rowset, accessor or schema state with the metadata and properties actually granted by the provider.
  4. For DB_E_NOTPREPARED, 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.
  5. For DB_E_NOTPREPARED, reproduce the issue with the smallest command, rowset or definition operation that preserves the same contract boundary.
  6. For DB_E_NOTPREPARED, apply one evidence-backed correction, then verify that the operation succeeds and does not merely change into a nearby HRESULT.

Corrective actions

  • Action 1 for DB_E_NOTPREPARED: call Prepare and require success before prepared-only metadata or execution paths.
  • Action 2 for DB_E_NOTPREPARED: return to the unprepared state explicitly when command text changes.
  • Action 3 for DB_E_NOTPREPARED: do not cache a prepared-state flag independently of the command object.

Practical incident

A metadata loader sets SQL and immediately calls a prepared-command columns method; inserting a successful Prepare step prevents DB_E_NOTPREPARED. The diagnostic value comes from retaining DB_E_NOTPREPARED together with the failing interface and object state, not from reducing every provider result to “database error”.

Implementation guidance

Code handling DB_E_NOTPREPARED 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_NOTPREPARED, handles such as HACCESSOR, HROW, HCHAPTER and provider-specific region tokens must never be treated as portable integers across object lifetimes.

When DB_E_NOTPREPARED 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_NOTPREPARED, do not log passwords, access tokens, complete SQL text or unrestricted row values merely to make the event easier to search.

Retry and recovery policy

Retry rule for DB_E_NOTPREPARED: retry after a successful Prepare on the current command definition. A safe DB_E_NOTPREPARED retry must use a changed input, object generation, provider capability or state transition. If the call returning DB_E_NOTPREPARED could have created, updated, deleted or copied data, determine partial completion before replaying it.

For DB_E_NOTPREPARED, use bounded retries and preserve cancellation. For DB_E_NOTPREPARED, configuration and contract failures should normally fail fast; concurrency, resource or transient state failures may justify retry only after their stated precondition changes.

Difference from related HRESULT values

DB_E_NOCOMMAND means no command text is set, while DB_E_NOTPREPARED means text exists but the command has not reached the required prepared state. Keep these outcomes separate in telemetry and user-facing remediation because DB_E_NOTPREPARED requires a different next action.

Official Microsoft references

Looking for a different code? Search another status or error code.