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

Ensure the container was created through this network (register/agent.join) before requesting it; re-create it if the network restarted.

hcengineering/platform · error

Container ${target} not found

Error message

Container ${target} not found

What it means

Network.request looks the target container up in the network's local _containers map before dispatching the operation to the owning agent. If the uuid is absent from the map the network throws, since it has no record of which agent hosts that container. This is the network-level equivalent of the agent's own container-not-found error.

Source

Thrown at foundations/net/packages/core/src/network.ts:110

    }))
  }

  async kinds (): Promise<ContainerKind[]> {
    return Array.from(this._agents.values())
      .map((it) => it.kinds)
      .flatMap((it) => it)
  }

  async list (kind?: ContainerKind): Promise<ContainerRecord[]> {
    return Array.from(this._containers.values())
      .filter((it) => kind === undefined || it.record.kind === kind)
      .map((it) => it.record)
  }

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

  async register (record: AgentRecord, agent: NetworkAgent): Promise<ContainerUuid[]> {
    const newContainers: ContainerRecord[] = record.containers
    const newContainersMap = new Map<ContainerUuid, ContainerRecordImpl>(
      newContainers.map((record) => [
        record.uuid,
        {
          record,
          request: { kind: record.kind },
          endpoint: record.endpoint,
          clients: new Set<ClientUuid>([]),
          agent: null as any // Temporarily
        }
      ])
    )

View on GitHub (pinned to 63e28dc964)

Solutions

Ensure the container was created through this network (register/agent.join) before requesting it; re-create it if the network restarted.
Re-resolve the container: request a new instance of the same kind so the network can schedule it and return a fresh uuid.
Check that the owning agent is still connected; reconnect it so its container records are re-registered.
Persist uuids only across restarts if the network does; otherwise treat uuids as ephemeral and refetch.

Example fix

// before
await network.request(unknownUuid, 'run', payload) // throws if pruned
// after
const uuid = (await network.getContainer(clientId, kind, options)).uuid
await network.request(uuid, 'run', payload)

Defensive patterns

Strategy: try-catch

Validate before calling

if (!network.hasContainer?.(uuid)) {
  const fresh = await network.getContainer(clientId, kind, options)
  // use fresh.uuid instead of the stale one
}

Type guard

function containerExists(uuid: string, network: Network): boolean {
  return typeof uuid === 'string' && network.containers?.has?.(uuid) === true
}

Try / catch

try {
  return await network.request(uuid, op, data)
} catch (e) {
  if ((e as Error).message === `Container ${uuid} not found`) {
    const rec = await network.getContainer(clientId, kind, options)
    return await network.request(rec.record.uuid, op, data)
  }
  throw e
}

Prevention

Re-resolve containers after any network/agent restart instead of reusing persisted uuids.
Listen for agent-disconnect events and invalidate cached uuids of that agent's containers.
Release containers explicitly when done to keep uuid usage intentional.
Keep one network instance per environment to avoid uuid confusion across dev/prod.

When it happens

Trigger: Calling network.request(target, operation, data) with a uuid that was never registered via network.register/agent join, or one that was removed (container released, agent disconnected, records pruned).

Common situations: Agent left the network and its containers were dropped; client kept a uuid across a network restart; name/uuid mismatch between environments (dev vs prod networks); sending requests before register() finished populating _containers.

Related errors

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