{"record":{"id":"2bb34cb0c2c7d29b","repo":"google-gemini/gemini-cli","slug":"unexpected-state-neither-agent-card-json-nor-agen","errorCode":null,"errorMessage":"Unexpected state: neither agent_card_json nor agent_card_url present on remote agent","messagePattern":"Unexpected state: neither agent_card_json nor agent_card_url present on remote agent","errorType":"exception","errorClass":"AgentLoadError","httpStatus":null,"severity":"critical","filePath":"packages/core/src/agents/agentLoader.ts","lineNumber":540,"sourceCode":"        ? convertFrontmatterAuthToConfig(markdown.auth)\n        : undefined,\n      inputConfig,\n      metadata,\n    };\n\n    if (\n      'agent_card_json' in markdown &&\n      markdown.agent_card_json !== undefined\n    ) {\n      base.agentCardJson = markdown.agent_card_json;\n      return base;\n    }\n    if ('agent_card_url' in markdown && markdown.agent_card_url !== undefined) {\n      base.agentCardUrl = markdown.agent_card_url;\n      return base;\n    }\n\n    throw new AgentLoadError(\n      metadata?.filePath || 'unknown',\n      'Unexpected state: neither agent_card_json nor agent_card_url present on remote agent',\n    );\n  }\n\n  // If a model is specified, use it. Otherwise, inherit\n  const modelName = markdown.model || 'inherit';\n\n  const mcpServers: Record<string, MCPServerConfig> = {};\n  if (markdown.mcp_servers) {\n    for (const [name, config] of Object.entries(markdown.mcp_servers)) {\n      let authProviderType: AuthProviderType | undefined = undefined;\n      let oauth: MCPOAuthConfig | undefined = undefined;\n\n      if (config.auth) {\n        if (config.auth.type === 'google-credentials') {\n          authProviderType = AuthProviderType.GOOGLE_CREDENTIALS;\n          oauth = {","sourceCodeStart":522,"sourceCodeEnd":558,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/agentLoader.ts#L522-L558","documentation":"markdownToAgentDefinition builds a RemoteAgentDefinition only after the frontmatter passed schema validation, so a remote agent is expected to carry either agent_card_json or agent_card_url. Reaching this throw means the schema accepted a remote-kind object without either field - an invariant violation indicating a gap between markdownFrontmatterSchema and this builder. The 'Unexpected state' wording marks it as a shouldn't-happen condition.","triggerScenarios":"The schema union matched a remote branch that does not enforce agent_card_json/agent_card_url as required; a discriminator matched 'remote' via a different key; an extension to the schema added a remote variant without the card fields; the frontmatter was constructed programmatically and bypassed strict parsing.","commonSituations":"A schema refactor loosened the remote branch; a test constructed a FrontmatterAgentDefinition object directly without running the schema; a feature added a new remote kind without updating the builder's guard.","solutions":["If authoring a file, add either agent_card_url or agent_card_json to the remote frontmatter.","If this fires from a valid file, the schema is too permissive - tighten markdownFrontmatterSchema's remote branch to require one card field.","If constructing the object in code, run it through parseAgentMarkdown/validate first.","Report as a loader bug since the schema should have caught it earlier."],"exampleFix":"# before\n---\nname: remote-svc\nkind: remote\n# no card field\n---\n\n# after\n---\nname: remote-svc\nkind: remote\nagent_card_url: https://svc.example/.well-known/agent-card.json\n---","handlingStrategy":"validation","validationCode":"function hasRemoteCardField(md: { kind?: string }): boolean {\n  return 'agent_card_json' in md || 'agent_card_url' in md;\n}\nif (frontmatter.kind === 'remote' && !hasRemoteCardField(frontmatter)) {\n  throw new Error('Remote agent requires agent_card_json or agent_card_url.');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include agent_card_url (or agent_card_json) on remote agents.","If this fires despite a valid file, tighten the schema's remote branch.","Construct remote definitions only through parseAgentMarkdown."],"tags":["agent-loader","remote-agent","invariant","schema-gap"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}