deepseek-ai/deepseek-harness · error · TypertGatewayError

lookup-not-found

lookup-not-found

Error message

lookup provider ${JSON.stringify(key)} did not resolve the requested identity

What it means

The lookup provider resolved without throwing but returned undefined: the wire id in the parameter's field does not correspond to any live Host object. This is the 404-equivalent for lookup parameters — the endpoint, provider, and request shape are all fine, but that id has no target to bind.

Source

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

        endpoint,
        `lookup provider ${JSON.stringify(key)} does not match its strict definition`,
        { field: parameter.wire },
      )
    }
    let resolved: unknown
    try {
      resolved = await provider.resolve(value)
    } catch (cause) {
      if (cause instanceof TypertLookupFailure) throw cause
      throw new TypertGatewayError(
        'lookup-failed',
        endpoint,
        `lookup provider ${JSON.stringify(key)} failed`,
        { cause, field: parameter.wire },
      )
    }
    if (resolved === undefined) {
      throw new TypertGatewayError(
        'lookup-not-found',
        endpoint,
        `lookup provider ${JSON.stringify(key)} did not resolve the requested identity`,
        { field: parameter.wire },
      )
    }
    return resolved
  }
}

function rpcFailure(error: unknown): ConnectionRpcResult {
  if (error instanceof RemoteInvocationCancelled) {
    return {
      ok: false,
      error: { code: 'cancelled', message: error.message, details: {} },
    }
  }
  if (error instanceof TypertLookupFailure) {

View on GitHub (pinned to b150a551b8)

Solutions

  1. Refresh the id from its source (re-list, re-open the owning resource) and retry with a current value.
  2. If the entity should exist, verify it through the owning service directly, then check the provider's resolver coverage.
  3. Map it to a clean 404 in the client; do not retry the same id unchanged.

Example fix

// before — firing with an id cached long ago
await remote.docs.read({ docId })
// → lookup-not-found after the document was deleted

// after — validate against the current listing first
const docs = await remote.docs.list()
if (!docs.some(doc => doc.id === docId)) throw new NotFound(`document ${docId}`)
await remote.docs.read({ docId })
Defensive patterns

Strategy: try-catch

Validate before calling

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

// Host-side callers can pre-check one id through the provider before the RPC.
async function idResolves(provider: TypertLookupProvider, id: unknown): Promise<boolean> {
  return (await provider.resolve(id)) !== undefined
}

Type guard

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

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

Try / catch

try {
  await gateway.invoke(request)
} catch (error) {
  if (error instanceof TypertGatewayError && error.code === 'lookup-not-found') {
    // expected miss: surface a domain 404 keyed by error.field, never a 500
    const id = (request.args as Record<string, unknown>)[error.field ?? '']
    throw new NotFoundError(`${error.field} ${JSON.stringify(id)}`)
  }
  throw error
}

Prevention

When it happens

Trigger: Passing an id for a deleted, not-yet-created, or foreign-environment object in a lookup parameter — for example a docId whose document was removed after the client last listed it, or an id from a different deployment.

Common situations: Client holds stale ids after another user or process deleted the entity; race between create and first use; ids copied between dev and prod; hand-built request payloads with typo'd ids.

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/b33f5f5ab3dcab07. Report an issue: GitHub.