deepseek-ai/deepseek-harness · error · TypertGatewayError

context-failed

context-failed

Error message

Context provider ${JSON.stringify(invocation.context)} failed

What it means

The Host Context provider's resolve(identity) threw an exception that is not a TypertLookupFailure (those keep their own failure identity on the wire). The Gateway wraps the original error as context-failed with the cause attached and the identity wire field in field — an infrastructure failure inside the provider (backing store, resolver bug), not a malformed request.

Source

Thrown at packages/api/gateway/src/index.ts:389

        `Context provider ${JSON.stringify(invocation.context)} is unavailable`,
      )
    }
    if (provider.wire !== invocation.wire
      || (invocation.codec.mode === 'strict' && provider.wireTypeSymbol !== invocation.codec.typeSymbol)) {
      throw new TypertGatewayError(
        'provider-mismatch',
        endpoint,
        `Context provider ${JSON.stringify(invocation.context)} does not match its strict definition`,
        { field: invocation.wire },
      )
    }
    const identity = decode(invocation.codec, args[invocation.wire], 'input-invalid', endpoint, invocation.wire)
    let context: Context | undefined
    try {
      context = await provider.resolve(identity)
    } catch (cause) {
      if (cause instanceof TypertLookupFailure) throw cause
      throw new TypertGatewayError(
        'context-failed',
        endpoint,
        `Context provider ${JSON.stringify(invocation.context)} failed`,
        { cause, field: invocation.wire },
      )
    }
    if (context === undefined) {
      throw new TypertGatewayError(
        'context-not-found',
        endpoint,
        `Context provider ${JSON.stringify(invocation.context)} did not resolve the requested identity`,
        { field: invocation.wire },
      )
    }
    return context
  }

  private async resolveParameter(

View on GitHub (pinned to b150a551b8)

Solutions

  1. Inspect error.cause — the provider's original exception carries the real failure; fix that (restore the store, repair permissions, fix the bug).
  2. In the provider, return undefined for well-formed but unknown identities so they surface as context-not-found instead of context-failed.
  3. If the cause is transient (network blip, store restart), retry the invoke once the backing service is healthy.

Example fix

// before — provider throws on missing rows, so absent ids surface as context-failed
resolve: async (id: string) => {
  const row = await store.get(`session:${id}`) // store.get rejects on not-found
  return toContext(row)
}
// after — absent identity returns undefined → context-not-found; only real errors throw
resolve: async (id: string) => {
  const row = await store.get(`session:${id}`)
  return row === null ? undefined : toContext(row)
}
Defensive patterns

Strategy: try-catch

Type guard

import { TypertGatewayError } from '@deepseek-ai/dsh-api-gateway'

function isContextFailed(error: unknown): error is TypertGatewayError {
  return error instanceof TypertGatewayError && error.code === 'context-failed'
}

Try / catch

try {
  await gateway.invoke(request)
} catch (error) {
  if (error instanceof TypertGatewayError && error.code === 'context-failed') {
    // infrastructure failure: log the cause chain and surface as 5xx, never as a business 404
    logger.error('context provider failure', { endpoint: error.endpoint, field: error.field, cause: error.cause })
    throw error
  }
  throw error
}

Prevention

When it happens

Trigger: provider.resolve awaiting a database or file lookup that rejects (session store down, EACCES on the state directory), or resolver code throwing on an unexpected internal state, while resolveReceiverContext builds the receiver Context for a context-scoped endpoint.

Common situations: Session/state store outage behind the provider; a resolver that throws instead of returning undefined for unknown ids; transient I/O errors; unhandled rejections inside provider code.

Related errors

AI-assisted analysis of deepseek-ai/deepseek-harness@b150a551b8 (2026-08-24). Data as JSON: /api/errors/025269827686cc57. Report an issue: GitHub.