| Previous | Next |
| hrInvalidPath | hrTooManyOpenDatabases |
hrRecordTooBig
Where the operation crossed the contract
For hrRecordTooBig, the symbolic name points to a precise ESE precondition that should be verified before any retry. The decisive boundary is the assembled row exceeds the record-size budget after fixed, variable, tagged, and key overhead are considered.
This result is the legacy Directory Service backup/restore HRESULT form of the ESE condition normally written as JET_errRecordTooBig. Preserve the original value 0xC8000402 when a wrapper also exposes a signed JET_ERR.
The key comparison for this HRESULT is this: hrColumnDoesNotFit is tied to a particular field update; this code reflects the completed record size. The first useful observation is to measure each column payload, null state, multivalue count, and schema overhead for the failing row. This evidence separates schema definition, row-size accounting, null semantics, multivalue selection, and stale column IDs.
Reconstruct the engine state
A useful trace for this HRESULT should preserve the first failing operation and the state of the column schema, row-size accounting, tagged/multivalued storage, and column identifiers.
- Code-specific observation: measure each column payload, null state, multivalue count, and schema overhead for the failing row.
- the complete row-size contribution from fixed, variable, tagged, and long-value data; associate it with this result rather than with a later generic exception.
- JET_COLUMNDEF fields, flags, code page, maximum length, and column ID origin; associate it with this result rather than with a later generic exception.
- the encoded value length, null/empty state, and itag sequence; associate it with it rather than with a later generic exception.
Log lengths, hashes, IDs, flags, and redacted samples where appropriate.
The ESE objects in play
| Diagnostic layer | column schema, row-size accounting, tagged/multivalued storage, and column identifiers |
|---|---|
| Typical API surface | JetAddColumn, JetDeleteColumn, JetSetColumn, JetRetrieveColumn, and JET_COLUMNDEF |
| Code-specific boundary | the assembled row exceeds the record-size budget after fixed, variable, tagged, and key overhead are considered |
| First corrective direction | move large payloads to supported long-value columns or split the logical record without changing keys blindly |
Column IDs are metadata scoped to a table and should be refreshed after schema changes. Null, zero-length, deletion, and missing multivalue instances are distinct states.
Repair without destroying evidence
- Freeze the failing request context and record it,
0xC8000402, the Jet API name, and the current instance/session ownership. - Verify the code-specific precondition: measure each column payload, null state, multivalue count, and schema overhead for the failing row.
- Apply the narrow correction: move large payloads to supported long-value columns or split the logical record without changing keys blindly.
- Before retrying it, reconcile column metadata, row layout, and the exact stored value state.
- Repeat the smallest read-only or disposable test that exercises the corrected precondition; then confirm both the returned HRESULT and the resulting database, cursor, or file state.
Do not collapse these codes together
For this HRESULT, hrColumnDoesNotFit is tied to a particular field update; this code reflects the completed record size. The following neighboring results belong to the same broad subsystem but mark different boundaries:
hrNullInvalid | the target column definition requires a non-null value |
|---|---|
hrTaggedNotNULL | a tagged-column operation used null semantics that are not valid for this representation or engine version |
hrInvalidColumnType | the JET_coltyp value or its option combination is unsupported for this column definition |
Keep it in the incident record; replacing it with “database error” hides whether the next step is handle renewal, schema correction, lock reconciliation, or file preservation.
Developer-facing acceptance test
Build a focused test that reproduces it at the column schema, row-size accounting, tagged/multivalued storage, and column identifiers layer. Record the precondition, execute one API call, and assert the HRESULT plus the resulting handle and transaction state. The corrected test should change only the decisive condition—the assembled row exceeds the record-size budget after fixed, variable, tagged, and key overhead are considered—and should prove that cleanup is safe if the call still fails.
Actions that can hide or worsen the problem
- Do not alter the column schema in place without a migration and rollback plan.
- Do not collapse null, zero-length data, missing value, and tagged-value deletion into one state.
Technical references
- JetAddColumn — used to verify the ESE object model, API ordering, or error family relevant to it.
- JetSetColumn
- JetRetrieveColumn
- JET_COLUMNDEF
- Microsoft: JET_ERR enumeration
Looking for a different code? Search another status or error code.