{"record":{"id":"5397866a9228e121","repo":"paperclipai/paperclip","slug":"agentcore-profile-unavailable","errorCode":"agentcore_profile_unavailable","errorMessage":"AWS AgentCore profile is missing ${name}. Run aws-agentcore:provision and aws-agentcore:lab.","messagePattern":"AWS AgentCore profile is missing (.+?)\\. Run aws-agentcore:provision and aws-agentcore:lab\\.","errorType":"http","errorClass":"RouteError","httpStatus":503,"severity":"error","filePath":"packages/paperclip-runner/scripts/capability-issue-thread-server.mjs","lineNumber":330,"sourceCode":"      503,\n      \"managed_profile_unavailable\",\n      \"The selected Claude Managed profile is not fully qualified on this Runner Lab server.\",\n    );\n  }\n  return {\n    profileId,\n    anthropicAgentId,\n    agentVersion,\n    environmentId,\n    betaVersion: \"managed-agents-2026-04-01\",\n    maxSessionListCostUsd: configuration.maxSessionListCostUsd,\n  };\n}\n\nfunction resolveAgentCoreProfile(configuration) {\n  const required = (name) => {\n    const value = process.env[name]?.trim();\n    if (!value) throw new RouteError(503, \"agentcore_profile_unavailable\", `AWS AgentCore profile is missing ${name}. Run aws-agentcore:provision and aws-agentcore:lab.`);\n    return value;\n  };\n  const profileId = required(\"PAPERCLIP_AWS_AGENTCORE_PROFILE_ID\");\n  if (profileId !== configuration.agentCoreProfileId) {\n    throw new RouteError(400, \"agentcore_profile_not_found\", \"The selected AWS AgentCore profile is not configured on this Runner Lab server.\");\n  }\n  return {\n    profileId,\n    region: required(\"AWS_REGION\"),\n    accountId: required(\"PAPERCLIP_AWS_AGENTCORE_ACCOUNT_ID\"),\n    harnessArn: required(\"PAPERCLIP_AWS_AGENTCORE_HARNESS_ARN\"),\n    harnessVersion: required(\"PAPERCLIP_AWS_AGENTCORE_HARNESS_VERSION\"),\n    endpointArn: required(\"PAPERCLIP_AWS_AGENTCORE_ENDPOINT_ARN\"),\n    endpointQualifier: required(\"PAPERCLIP_AWS_AGENTCORE_ENDPOINT_QUALIFIER\"),\n    agentRuntimeArn: required(\"PAPERCLIP_AWS_AGENTCORE_RUNTIME_ARN\"),\n    memoryArn: required(\"PAPERCLIP_AWS_AGENTCORE_MEMORY_ARN\"),\n    memoryId: required(\"PAPERCLIP_AWS_AGENTCORE_MEMORY_ID\"),\n    invocationRoleArn: required(\"PAPERCLIP_AWS_AGENTCORE_INVOCATION_ROLE_ARN\"),","sourceCodeStart":312,"sourceCodeEnd":348,"githubUrl":"https://github.com/paperclipai/paperclip/blob/5716fe907e596ce73501408fc6efdb19fb61edf2/packages/paperclip-runner/scripts/capability-issue-thread-server.mjs#L312-L348","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n# no agentcore vars in server env\n// after\nexport PAPERCLIP_AWS_AGENTCORE_PROFILE_ID=prof-123\nexport AWS_REGION=us-east-1\nexport PAPERCLIP_AWS_AGENTCORE_ACCOUNT_ID=123456789012\nexport PAPERCLIP_AWS_AGENTCORE_HARNESS_ARN=arn:aws:lambda:us-east-1:123456789012:function:harness","handlingStrategy":"validation","validationCode":"const REQUIRED_AGENTCORE_VARS = [\n  \"PAPERCLIP_AWS_AGENTCORE_PROFILE_ID\",\n  \"AWS_REGION\",\n  \"PAPERCLIP_AWS_AGENTCORE_ACCOUNT_ID\",\n  \"PAPERCLIP_AWS_AGENTCORE_HARNESS_ARN\",\n];\nconst missing = REQUIRED_AGENTCORE_VARS.filter((n) => !process.env[n]?.trim());\nif (missing.length) throw new Error(`AgentCore env missing: ${missing.join(\", \")} — run aws-agentcore:provision and aws-agentcore:lab`);","typeGuard":"function hasAgentCoreEnv(names, env = process.env) {\n  return names.every((n) => typeof env[n] === \"string\" && env[n].trim().length > 0);\n}","tryCatchPattern":"try {\n  await configureHarness(cfg);\n} catch (e) {\n  if (e.code === \"agentcore_profile_unavailable\") {\n    // 503: run provisioning out-of-band, then retry once\n    await exec(\"aws-agentcore:provision && aws-agentcore:lab\");\n    await configureHarness(cfg);\n  } else throw e;\n}","preventionTips":["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."],"tags":["env-var","aws","agentcore","http-503","server-config"],"backgroundTag":"missing-env-var","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"}