deepseek-ai/deepseek-harness · error · TypertGatewayError

context-not-found

context-not-found

Error message

Context provider ${JSON.stringify(invocation.context)} did not resolve the requested identity

What it means

The Host Context provider resolved without throwing but returned undefined: the identity carried by the invocation's wire field does not map to any live scoped Context. This is the 404-equivalent for context-scoped remotes — the request shape was valid and the provider is healthy, but that identity no longer (or never) exists on this host.

Source

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

        `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(
    parameter: InvocationParameterDescriptor,
    args: Readonly<Record<string, unknown>>,
    endpoint: string,
  ): Promise<unknown> {
    // An absent field reached assertExactArguments' allowance, so this parameter
    // takes undefined; a present-but-undefined field is not JSON-safe input and
    // still fails decode. Lookup ids are never omissible, so absence here only
    // ever belongs to a json parameter.

View on GitHub (pinned to b150a551b8)

Solutions

Re-acquire a fresh identity (re-run the session/terminal bootstrap) and retry the call once.
If the identity should be valid, check host affinity — route to the node that owns the scoped Context or restore its backing store.
Treat it as a terminal 404 in client logic: do not blind-retry the same identity.

Example fix

// before — one-shot call with a possibly stale identity
await scopedRemote.send({ text })
// → context-not-found after the scoped Context expired

// after — fall back to a fresh identity and retry once
try {
  await scopedRemote.send({ text })
} catch (error) {
  if (isContextNotFound(error)) {
    await reestablishScope()
    await scopedRemote.send({ text })
  } else throw error
}

Defensive patterns

Strategy: fallback

Validate before calling

import type { TypertHostContextProvider } from '@deepseek-ai/dsh-typert-protocol'

// Host-side callers can pre-validate the identity against the provider.
async function identityIsLive(provider: TypertHostContextProvider, id: unknown): Promise<boolean> {
  return (await provider.resolve(id)) !== undefined
}

Type guard

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

function isContextNotFound(error: unknown): error is TypertGatewayError {
  return error instanceof TypertGatewayError && error.code === 'context-not-found'
}

Try / catch

try {
  return await gateway.invoke(request)
} catch (error) {
  if (error instanceof TypertGatewayError && error.code === 'context-not-found') {
    const fresh = await reestablishScope() // fallback: new identity, single retry
    const args = { ...(request.args as Record<string, unknown>), [error.field ?? 'sessionId']: fresh }
    return gateway.invoke({ ...request, args })
  }
  throw error
}

Prevention

Refresh identities after host restarts and reconnections instead of persisting them indefinitely.
Expire client-side cached ids on the same TTL the scoped Context uses.
Map context-not-found onto your client's 404 handling path — never onto a generic internal-error path.

When it happens

Trigger: Calling a 'session:<ns>/<method>' endpoint with a sessionId whose session expired, was disposed, or belongs to a different host instance; using an identity captured before a host restart.

Common situations: Client reconnects after a server restart with a persisted session id; session TTL expiry mid-workflow; load-balanced routing sends the call to a node that does not hold that scoped Context; an id copied from another environment.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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