paperclipai/paperclip · error · RouteError

agentcore_profile_not_found

agentcore_profile_not_found

Error message

The selected AWS AgentCore profile is not configured on this Runner Lab server.

What it means

After required() confirms the profile ID env var exists, resolveAgentCoreProfile compares it with configuration.agentCoreProfileId from the request. An exact !== mismatch means the requested AWS AgentCore profile is not the one this Runner Lab server has provisioned, producing a 400 agentcore_profile_not_found. Like the Claude Managed equivalent, it separates 'profile unknown to this server' from 'server not provisioned' (the 503 case).

Source

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

  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"),
    contextBucket: required("PAPERCLIP_AWS_AGENTCORE_CONTEXT_BUCKET"),
    contextPrefix: required("PAPERCLIP_AWS_AGENTCORE_CONTEXT_PREFIX"),
    contextKmsKeyArn: required("PAPERCLIP_AWS_AGENTCORE_CONTEXT_KMS_KEY_ARN"),
    qualificationRevision: required("PAPERCLIP_AWS_AGENTCORE_QUALIFICATION_REVISION"),
    eventExpiryDays: 90,

View on GitHub (pinned to 5716fe907e)

Solutions

Update the request's agentCoreProfileId to exactly match the server's PAPERCLIP_AWS_AGENTCORE_PROFILE_ID env value.
Re-fetch the server's configured profile (via lab/status endpoints or config) and refresh any cached client/UI profile list.
Check for exact-match pitfalls: the comparison is case-sensitive and happens after trimming the env value only, so normalize client input too.
Point the client at the Runner Lab server that actually hosts the requested profile, or re-run aws-agentcore:provision to host the desired profile here.

Example fix

// before
PAPERCLIP_AWS_AGENTCORE_PROFILE_ID=prof-new
client: { "agentCoreProfileId": "prof-old" }
// after
client: { "agentCoreProfileId": "prof-new" }

Defensive patterns

Strategy: validation

Validate before calling

const serverProfile = process.env.PAPERCLIP_AWS_AGENTCORE_PROFILE_ID?.trim();
if (serverProfile && serverProfile !== requested.agentCoreProfileId) {
  throw new Error(`Requested AgentCore profile ${requested.agentCoreProfileId} not hosted here; server hosts ${serverProfile}`);
}

Type guard

function isHostedAgentCoreProfile(requestedId, serverEnv = process.env) {
  const hosted = serverEnv.PAPERCLIP_AWS_AGENTCORE_PROFILE_ID?.trim();
  return !hosted || hosted === requestedId;
}

Try / catch

try {
  await configureHarness(cfg);
} catch (e) {
  if (e.code === "agentcore_profile_not_found") {
    cfg.agentCoreProfileId = process.env.PAPERCLIP_AWS_AGENTCORE_PROFILE_ID?.trim();
    await configureHarness(cfg);
  } else throw e;
}

Prevention

Fetch the hosted profile ID from the server at session start instead of caching it in clients.
Normalize (trim, case) profile IDs on both client and server before comparing.
Re-sync client configs whenever the server's AgentCore profile is re-provisioned.
Distinguish per-environment profile IDs in config to avoid cross-env mismatches.

When it happens

Trigger: Client sends configuration.agentCoreProfileId="prof-old" while the server env PAPERCLIP_AWS_AGENTCORE_PROFILE_ID is "prof-new" (after trim); exact string comparison, so case/whitespace differences also fail.

Common situations: Profile re-provisioned with a new ID but clients kept the old one; dev and prod servers each host different profiles and a client config crosses environments; manual edit of the env var introducing a typo or trailing space; stale UI cache of profile IDs.

Related errors

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