What causes "Container ${target} not found" in hcengineering/platform?

Confirm the uuid is the one returned by the same agent instance (e.g. from agent.api.get(kind) or the network record), not one from another node.

hcengineering/platform · error

Container ${target} not found

Error message

Container ${target} not found

What it means

Agent.request resolves the target container via getContainer and delegates the operation to it. When the container UUID is not known to this agent, it throws instead of calling request on undefined. It indicates the caller is addressing a container this agent instance cannot see or no longer holds.

Source

Thrown at foundations/net/packages/core/src/agent.ts:254

        await (await current).container.terminate() // Await promise before terminating
      } else {
        await current.container.terminate()
      }
      return
    }

    // Also check stateless containers
    const stateless = this.statelessContainers.get(uuid)
    if (stateless !== undefined) {
      this.statelessContainers.delete(uuid)
      await stateless.container.terminate()
    }
  }

  async request (target: ContainerUuid, operation: string, data?: any): Promise<any> {
    const container = await this.getContainer(target)
    if (container === undefined) {
      throw new Error(`Container ${target} not found`)
    }
    return await container.request(operation, data)
  }
}

View on GitHub (pinned to 63e28dc964)

Solutions

Confirm the uuid is the one returned by the same agent instance (e.g. from agent.api.get(kind) or the network record), not one from another node.
Re-acquire the container: call get/create again to obtain a fresh uuid, then retry the request.
Check the agent's registered containers/records to see whether the target exists and under which agent.
In distributed setups, route the request through the network/discovery layer instead of the local agent so the correct agent handles it.

Example fix

// before
const result = await agent.request(staleUuid, 'compute', data)
// after
const [uuid] = await agent.api.get(kind, options)
const result = await agent.request(uuid, 'compute', data)

Defensive patterns

Strategy: try-catch

Validate before calling

const known = await agent.getContainer?.(target) // or track uuids you created
if (known === undefined) {
  console.warn('agent does not know container', target, '- re-acquiring')
}

Type guard

function isKnownContainer(uuid: string | undefined): uuid is string {
  return typeof uuid === 'string' && createdUuids.has(uuid)
}

Try / catch

try {
  return await agent.request(target, op, data)
} catch (e) {
  if ((e as Error).message === `Container ${target} not found`) {
    const [uuid] = await agent.api.get(kind, options) // re-acquire fresh container
    return await agent.request(uuid, op, data)
  }
  throw e
}

Prevention

Treat container uuids as ephemeral: always fetch from the same agent instance you call request on.
Clear cached uuids when an agent is released or restarted.
Log uuid provenance (which agent returned it) to catch cross-agent routing mistakes.
Prefer network-level request routing in multi-agent setups instead of direct agent calls.

When it happens

Trigger: Calling agent.request(target, operation, data) with a ContainerUuid that was never registered on this agent, was released, or belongs to another agent/network node. getContainer returning undefined for the uuid.

Common situations: Using a stale container uuid after release/agent restart; routing a request to the wrong agent in a multi-agent deployment; copy-pasted or truncated uuid; race where the container record was evicted between obtaining the uuid and calling request.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/a26d87b8542f5073. Report an issue: GitHub.