paperclipai/paperclip · error

Anthropic did not return a usable pinned Agent version

Error message

Anthropic did not return a usable pinned Agent version

What it means

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.

Source

Thrown at cli/src/commands/managed-agent.ts:352

    resolveAgent(validated.anthropicApiKey, normalizedOptions),
  ]);
  const agentId = String(agent.id ?? "");
  const environmentId = String(environment.id ?? "");
  if (!agentId || !environmentId) {
    throw new Error("Anthropic did not return usable Agent and Environment identities");
  }

  const versions = await listAll(
    validated.anthropicApiKey,
    `/v1/agents/${encodeURIComponent(agentId)}/versions`,
  );
  const version = normalizedOptions.agentVersion
    ?? String(agent.version ?? versions.at(-1)?.version ?? "");
  const pinnedAgent = version
    ? versions.find((entry) => String(entry.version) === version)
    : undefined;
  if (!version || !pinnedAgent) {
    throw new Error("Anthropic did not return a usable pinned Agent version");
  }
  if (String(pinnedAgent.id ?? "") !== agentId) {
    throw new Error("Anthropic pinned Agent version identity does not match the selected Agent");
  }
  assertSafeManagedAgent(pinnedAgent);
  assertManagedAgentModel(pinnedAgent, normalizedOptions.model);

  const qualification = {
    probedAt: new Date().toISOString(),
    betaVersion: CLAUDE_MANAGED_BETA_VERSION,
    environmentPolicy: "limited_no_hosts_no_packages",
    agentCapabilities: "no_tools_no_mcp_no_skills_no_multiagent",
  };
  const profile = {
    profileKey: normalizedOptions.profileKey,
    displayName: normalizedOptions.displayName,
    anthropicAgentId: agentId,
    agentVersion: version,

View on GitHub (pinned to 5716fe907e)

Solutions

  1. Omit the explicit agentVersion so the latest listed version is pinned automatically.
  2. List GET /v1/agents/:id/versions and pin one of the actually returned version numbers.
  3. If the agent was recreated, re-run setup so agent.version/versions are re-read for the new agent.
  4. Verify the agentVersion you pass matches the type/format the API returns (number vs string).

Example fix

// before: stale pinned version after agent recreation
const version = "7"; // no longer exists
// after: let setup pin latest
const version = normalizedOptions.agentVersion ?? String(agent.version ?? versions.at(-1)?.version ?? "");
Defensive patterns

Strategy: validation

Validate before calling

// verify the requested version exists before setup
const versions = await listAll(key, `/v1/agents/${agentId}/versions`);
if (requestedVersion && !versions.some(v => String(v.version) === String(requestedVersion))) {
  throw new Error(`Version ${requestedVersion} not found; available: ${versions.map(v => v.version).join(", ")}`);
}

Type guard

function versionIsPinnable(versions: Array<{ version: unknown }>, wanted?: string): boolean {
  if (!wanted) return versions.length > 0;
  return versions.some(v => String(v.version) === wanted);
}

Try / catch

try {
  await setupManagedAgent({ ...options, agentVersion: pinned });
} catch (e) {
  if (e instanceof Error && e.message.includes("usable pinned Agent version")) {
    // retry letting setup auto-select the latest version
    await setupManagedAgent({ ...options, agentVersion: undefined });
  } else throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of paperclipai/paperclip@5716fe907e (2026-09-02). Data as JSON: /api/errors/e7445b150cbfface. Report an issue: GitHub.