{"record":{"id":"57b3bc8ce9bb12fe","repo":"sipeed/picoclaw","slug":"no-agent-available-for-route-agent-id-s","errorCode":null,"errorMessage":"no agent available for route (agent_id=%s)","messagePattern":"no agent available for route \\(agent_id=(.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/agent_message.go","lineNumber":230,"sourceCode":"\t\t\t\t\"session_key\": opts.Dispatch.SessionKey,\n\t\t\t\t\"skills\":      strings.Join(pending, \",\"),\n\t\t\t})\n\t}\n\n\treturn al.runAgentLoop(ctx, agent, opts)\n}\n\nfunc (al *AgentLoop) resolveMessageRoute(msg bus.InboundMessage) (routing.ResolvedRoute, *AgentInstance, error) {\n\tregistry := al.GetRegistry()\n\tinboundCtx := normalizedInboundContext(msg)\n\troute := registry.ResolveRoute(inboundCtx)\n\n\tagent, ok := registry.GetAgent(route.AgentID)\n\tif !ok {\n\t\tagent = registry.GetDefaultAgent()\n\t}\n\tif agent == nil {\n\t\treturn routing.ResolvedRoute{}, nil, fmt.Errorf(\"no agent available for route (agent_id=%s)\", route.AgentID)\n\t}\n\n\treturn route, agent, nil\n}\n\nfunc (al *AgentLoop) allocateRouteSession(route routing.ResolvedRoute, msg bus.InboundMessage) session.Allocation {\n\treturn session.AllocateRouteSession(session.AllocationInput{\n\t\tAgentID:       route.AgentID,\n\t\tContext:       normalizedInboundContext(msg),\n\t\tSessionPolicy: route.SessionPolicy,\n\t})\n}\n\nfunc (al *AgentLoop) processSystemMessage(\n\tctx context.Context,\n\tmsg bus.InboundMessage,\n) (string, error) {\n\tif msg.Channel != \"system\" {","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/pkg/agent/agent_message.go#L212-L248","documentation":"Every inbound message is routed: AgentRegistry.ResolveRoute maps the inbound context (channel/chat) to a ResolvedRoute with an AgentID; the loop then tries GetAgent(route.AgentID) and falls back to GetDefaultAgent(). This error fires when the routed agent_id does not exist in the registry AND no fallback agent exists — there is literally no agent to hand the message to.","triggerScenarios":"A routing rule or channel-to-agent mapping resolves to an agent id that is not in agents.list, while the registry is empty or contains no other usable agent for the fallback. The %s in the message shows the unresolved agent_id.","commonSituations":"Typo in a routing rule's agent id; an agent removed or renamed in config while routing rules still point at the old id; agents.list failed to load (provider errors) so even the fallback is missing.","solutions":["Look at the agent_id in the message and either add that agent to config or fix the routing entry that references it","Keep at least one healthy agent registered so the GetDefaultAgent fallback can absorb unknown routes","Validate routing rules against agents.list ids at startup (CI config lint)","Restart picoclaw after fixing config; routes are resolved per message so no cached state is involved"],"exampleFix":"// config — before: route points at nonexistent agent id\n\"routing\": { \"rules\": [ { \"channel\": \"telegram\", \"agent_id\": \"asistant\" } ] }\n\"agents\": { \"list\": [ { \"id\": \"assistant\", \"model_name\": \"gpt-4o-mini\" } ] }\n\n// after: ids match\n\"routing\": { \"rules\": [ { \"channel\": \"telegram\", \"agent_id\": \"assistant\" } ] }\n\"agents\": { \"list\": [ { \"id\": \"assistant\", \"model_name\": \"gpt-4o-mini\" } ] }","handlingStrategy":"validation","validationCode":"ids := al.GetRegistry().ListAgentIDs()\nknown := make(map[string]bool, len(ids))\nfor _, id := range ids {\n    known[id] = true\n}\nfor _, rule := range cfg.Routing.Rules { // adapt to your routing config shape\n    if rule.AgentID != \"\" && !known[rule.AgentID] {\n        return fmt.Errorf(\"routing rule references unknown agent %q\", rule.AgentID)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep one healthy default agent registered so unknown routes fall back instead of failing","Lint routing rules against agents.list ids in CI","When removing/renaming an agent, grep config for its id before deploying"],"tags":["go","picoclaw","agents","routing","registry","config"],"backgroundTag":null,"analyzedSha":"49183d7e8daed0dba89ddbb6fcb60089401d9680","analyzedAt":"2026-08-15T21:55:41.315Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}