hcengineering/platform · error

Unknown method

Error message

Unknown method

What it means

The network client's requestHandler switch over agent/container operations reached default because the method did not match any known opNames case. It throws 'Unknown method'. Protocol mismatch between what the caller sent and the operations this client build supports.

Source

Thrown at foundations/net/packages/client/src/client.ts:178

      await send({ error: `Agent ${agentId} not found` })
      return
    }
    switch (method) {
      case opNames.getContainer:
        await send(await agent.get(agentParams[0], agentParams[1]))
        break
      case opNames.listContainers:
        await send(await agent.list(agentParams[0]))
        break
      case opNames.sendContainer:
        await send(await agent.request(agentParams[0], agentParams[1], agentParams[2]))
        break
      case opNames.terminate:
        await agent.terminate(agentParams[0] as ContainerUuid)
        await send('')
        break
      default:
        throw new Error('Unknown method')
    }
  }

  async onEvent (event: NetworkEvent): Promise<void> {
    // Handle container events
    // In case of container stopped, agent stopped or endpoint changed, we need to update direct connections to be re-established.
    await this.handleConnectionUpdates(event)

    // Handle container removal for stateless containers - attempt to re-register
    for (const containerEvent of event.containers) {
      if (containerEvent.event === NetworkEventKind.removed) {
        // Check if any of our agents have this container as stateless and need to re-register
        for (const agentRecord of this._agents.values()) {
          const agent = agentRecord.agent as any
          const statelessContainers = agent.statelessContainers as Map<ContainerUuid, any> | undefined
          if (statelessContainers !== undefined && statelessContainers.has(containerEvent.container.uuid)) {
            console.log(
              `HA: Container ${containerEvent.container.uuid} removed, attempting to re-register from agent ${agent.uuid}`

View on GitHub (pinned to 63e28dc964)

Solutions

1. Only send methods defined in opNames constants
2. Sync client and agent/server package versions
3. Extend requestHandler with a case for the new operation if it's a legitimate op
4. Validate the method name client-side before issuing the request

Example fix

// before
await client.request('restart-agent', [uuid]) // not implemented
// after
// use a supported op or add a case in client.requestHandler first
await client.request(opNames.terminate, [uuid])

const allowed = Object.values(opNames) as string[]
if (!allowed.includes(method)) {
  throw new Error(`Unsupported client op: ${method}`)
}

function isClientOp(method: string): method is typeof opNames[keyof typeof opNames] {
  return (Object.values(opNames) as string[]).includes(method)
}

try {
  await client.request(method, params)
} catch (e) {
  if (e instanceof Error && e.message === 'Unknown method') {
    logProtocolMismatch(method)
  } else { throw e }
}

When it happens

Trigger: Sending a request through the client connection with a method name outside the supported set (hello/stop/terminate/etc.), e.g. a typo, unsupported op, or op removed in this version.

Common situations: Upgraded agents sending ops an older client doesn't understand; custom ops invented by app code but not implemented in the handler; case mismatches vs opNames constants.

Related errors

• Unknown method${method}
• Unknown method${method}
• platform.status.BadRequest
• INVALID_PROTOCOL
• Unknown message format:

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