{"record":{"id":"e7445b150cbfface","repo":"paperclipai/paperclip","slug":"anthropic-did-not-return-a-usable-pinned-agent-ver","errorCode":null,"errorMessage":"Anthropic did not return a usable pinned Agent version","messagePattern":"Anthropic did not return a usable pinned Agent version","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/commands/managed-agent.ts","lineNumber":352,"sourceCode":"    resolveAgent(validated.anthropicApiKey, normalizedOptions),\n  ]);\n  const agentId = String(agent.id ?? \"\");\n  const environmentId = String(environment.id ?? \"\");\n  if (!agentId || !environmentId) {\n    throw new Error(\"Anthropic did not return usable Agent and Environment identities\");\n  }\n\n  const versions = await listAll(\n    validated.anthropicApiKey,\n    `/v1/agents/${encodeURIComponent(agentId)}/versions`,\n  );\n  const version = normalizedOptions.agentVersion\n    ?? String(agent.version ?? versions.at(-1)?.version ?? \"\");\n  const pinnedAgent = version\n    ? versions.find((entry) => String(entry.version) === version)\n    : undefined;\n  if (!version || !pinnedAgent) {\n    throw new Error(\"Anthropic did not return a usable pinned Agent version\");\n  }\n  if (String(pinnedAgent.id ?? \"\") !== agentId) {\n    throw new Error(\"Anthropic pinned Agent version identity does not match the selected Agent\");\n  }\n  assertSafeManagedAgent(pinnedAgent);\n  assertManagedAgentModel(pinnedAgent, normalizedOptions.model);\n\n  const qualification = {\n    probedAt: new Date().toISOString(),\n    betaVersion: CLAUDE_MANAGED_BETA_VERSION,\n    environmentPolicy: \"limited_no_hosts_no_packages\",\n    agentCapabilities: \"no_tools_no_mcp_no_skills_no_multiagent\",\n  };\n  const profile = {\n    profileKey: normalizedOptions.profileKey,\n    displayName: normalizedOptions.displayName,\n    anthropicAgentId: agentId,\n    agentVersion: version,","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/paperclipai/paperclip/blob/5716fe907e596ce73501408fc6efdb19fb61edf2/cli/src/commands/managed-agent.ts#L334-L370","documentation":"After resolving the agent, setupManagedAgent pins a concrete agent version: the requested agentVersion, or agent.version, or the last listed version. It then requires that a version entry matching that number exists in /v1/agents/:id/versions. If the version is empty or no listed entry matches, setup aborts because credentials would reference a version that cannot be verified.","triggerScenarios":"Requesting --agent-version N where N is not among the versions returned by the versions endpoint; an agent with an empty versions list and no agent.version field; passing an agentVersion for a version created under a different agent or deleted.","commonSituations":"Typo or stale version number in config after the agent was recreated (versions restart); pinning a future version; agent whose version history was pruned; casing/type mismatch between requested version string and returned numeric versions.","solutions":["Omit the explicit agentVersion so the latest listed version is pinned automatically.","List GET /v1/agents/:id/versions and pin one of the actually returned version numbers.","If the agent was recreated, re-run setup so agent.version/versions are re-read for the new agent.","Verify the agentVersion you pass matches the type/format the API returns (number vs string)."],"exampleFix":"// before: stale pinned version after agent recreation\nconst version = \"7\"; // no longer exists\n// after: let setup pin latest\nconst version = normalizedOptions.agentVersion ?? String(agent.version ?? versions.at(-1)?.version ?? \"\");","handlingStrategy":"validation","validationCode":"// verify the requested version exists before setup\nconst versions = await listAll(key, `/v1/agents/${agentId}/versions`);\nif (requestedVersion && !versions.some(v => String(v.version) === String(requestedVersion))) {\n  throw new Error(`Version ${requestedVersion} not found; available: ${versions.map(v => v.version).join(\", \")}`);\n}","typeGuard":"function versionIsPinnable(versions: Array<{ version: unknown }>, wanted?: string): boolean {\n  if (!wanted) return versions.length > 0;\n  return versions.some(v => String(v.version) === wanted);\n}","tryCatchPattern":"try {\n  await setupManagedAgent({ ...options, agentVersion: pinned });\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"usable pinned Agent version\")) {\n    // retry letting setup auto-select the latest version\n    await setupManagedAgent({ ...options, agentVersion: undefined });\n  } else throw e;\n}","preventionTips":["Prefer omitting agentVersion so the latest listed version is pinned.","Re-read versions after any agent recreation; version numbers reset.","Compare versions as strings to dodge number/string mismatches.","Don't hardcode version numbers from another agent or environment."],"tags":["anthropic","agent","versioning","pinning","not-found"],"backgroundTag":"version-not-found","analyzedSha":"5716fe907e596ce73501408fc6efdb19fb61edf2","analyzedAt":"2026-09-02T18:44:00.616Z","contentChangedAt":"2026-09-02T18:44:00.616Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}