paperclipai/paperclip · error · RouteError

agentcore_profile_unavailable

agentcore_profile_unavailable

Error message

AWS AgentCore profile is missing ${name}. Run aws-agentcore:provision and aws-agentcore:lab.

What it means

resolveAgentCoreProfile defines a helper required(name) that reads an environment variable, trims it, and throws a 503 agentcore_profile_unavailable if it is empty, naming the missing variable and pointing at the aws-agentcore:provision and aws-agentcore:lab commands. It fires for the first missing variable checked: PAPERCLIP_AWS_AGENTCORE_PROFILE_ID, and subsequently for AWS_REGION, PAPERCLIP_AWS_AGENTCORE_ACCOUNT_ID, PAPERCLIP_AWS_AGENTCORE_HARNESS_ARN, etc. This is a server-side readiness error, not a client mistake.

Source

Thrown at packages/paperclip-runner/scripts/capability-issue-thread-server.mjs:330

      503,
      "managed_profile_unavailable",
      "The selected Claude Managed profile is not fully qualified on this Runner Lab server.",
    );
  }
  return {
    profileId,
    anthropicAgentId,
    agentVersion,
    environmentId,
    betaVersion: "managed-agents-2026-04-01",
    maxSessionListCostUsd: configuration.maxSessionListCostUsd,
  };
}

function resolveAgentCoreProfile(configuration) {
  const required = (name) => {
    const value = process.env[name]?.trim();
    if (!value) throw new RouteError(503, "agentcore_profile_unavailable", `AWS AgentCore profile is missing ${name}. Run aws-agentcore:provision and aws-agentcore:lab.`);
    return value;
  };
  const profileId = required("PAPERCLIP_AWS_AGENTCORE_PROFILE_ID");
  if (profileId !== configuration.agentCoreProfileId) {
    throw new RouteError(400, "agentcore_profile_not_found", "The selected AWS AgentCore profile is not configured on this Runner Lab server.");
  }
  return {
    profileId,
    region: required("AWS_REGION"),
    accountId: required("PAPERCLIP_AWS_AGENTCORE_ACCOUNT_ID"),
    harnessArn: required("PAPERCLIP_AWS_AGENTCORE_HARNESS_ARN"),
    harnessVersion: required("PAPERCLIP_AWS_AGENTCORE_HARNESS_VERSION"),
    endpointArn: required("PAPERCLIP_AWS_AGENTCORE_ENDPOINT_ARN"),
    endpointQualifier: required("PAPERCLIP_AWS_AGENTCORE_ENDPOINT_QUALIFIER"),
    agentRuntimeArn: required("PAPERCLIP_AWS_AGENTCORE_RUNTIME_ARN"),
    memoryArn: required("PAPERCLIP_AWS_AGENTCORE_MEMORY_ARN"),
    memoryId: required("PAPERCLIP_AWS_AGENTCORE_MEMORY_ID"),
    invocationRoleArn: required("PAPERCLIP_AWS_AGENTCORE_INVOCATION_ROLE_ARN"),

View on GitHub (pinned to 5716fe907e)

Solutions

Run aws-agentcore:provision and aws-agentcore:lab on the server to generate and export the required PAPERCLIP_AWS_AGENTCORE_* env vars, then restart the server.
Set the specific missing variable named in the message (e.g. PAPERCLIP_AWS_AGENTCORE_PROFILE_ID, AWS_REGION) in the server's service environment, not just your shell.
Confirm the process manager (systemd/docker) passes the env file through to the server process.
If AgentCore was not intended, switch the harness provider to avoid the AgentCore profile resolution path.

Example fix

// before
# no agentcore vars in server env
// after
export PAPERCLIP_AWS_AGENTCORE_PROFILE_ID=prof-123
export AWS_REGION=us-east-1
export PAPERCLIP_AWS_AGENTCORE_ACCOUNT_ID=123456789012
export PAPERCLIP_AWS_AGENTCORE_HARNESS_ARN=arn:aws:lambda:us-east-1:123456789012:function:harness

Defensive patterns

Strategy: validation

Validate before calling

const REQUIRED_AGENTCORE_VARS = [
  "PAPERCLIP_AWS_AGENTCORE_PROFILE_ID",
  "AWS_REGION",
  "PAPERCLIP_AWS_AGENTCORE_ACCOUNT_ID",
  "PAPERCLIP_AWS_AGENTCORE_HARNESS_ARN",
];
const missing = REQUIRED_AGENTCORE_VARS.filter((n) => !process.env[n]?.trim());
if (missing.length) throw new Error(`AgentCore env missing: ${missing.join(", ")} — run aws-agentcore:provision and aws-agentcore:lab`);

Type guard

function hasAgentCoreEnv(names, env = process.env) {
  return names.every((n) => typeof env[n] === "string" && env[n].trim().length > 0);
}

Try / catch

try {
  await configureHarness(cfg);
} catch (e) {
  if (e.code === "agentcore_profile_unavailable") {
    // 503: run provisioning out-of-band, then retry once
    await exec("aws-agentcore:provision && aws-agentcore:lab");
    await configureHarness(cfg);
  } else throw e;
}

Prevention

Run aws-agentcore:provision and aws-agentcore:lab as a mandatory post-deploy step.
Add a startup guard that fails fast when required PAPERCLIP_AWS_AGENTCORE_* / AWS_REGION vars are absent.
Set env vars in the service definition (systemd/docker), not only the interactive shell.
Document the full required env var list next to the deploy script.

When it happens

Trigger: Requesting an aws_agentcore harness when PAPERCLIP_AWS_AGENTCORE_PROFILE_ID (or any later required var such as AWS_REGION, PAPERCLIP_AWS_AGENTCORE_ACCOUNT_ID, PAPERCLIP_AWS_AGENTCORE_HARNESS_ARN) is unset or whitespace-only in the Runner Lab server environment.

Common situations: Server deployed without running aws-agentcore:provision and aws-agentcore:lab; env vars exported only in an interactive shell but not the service's environment; AWS_REGION unset in a container image; profile credentials wiped by a redeploy.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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