paperclipai/paperclip · error · PaperclipRunnerProviderProfileError

paperclip_runner_aws_agentcore_profile_invalid

paperclip_runner_aws_agentcore_profile_invalid

Error message

The qualified AWS AgentCore profile is missing ${key}.

What it means

The AWS AgentCore profile's stored configuration record must contain a complete set of ARNs/identifiers (region, accountId, harnessArn, harnessVersion, endpointArn, endpointQualifier, agentRuntimeArn, memoryArn, memoryId, invocationRoleArn, contextBucket, contextPrefix, contextKmsKeyArn, qualificationRevision, defaultModel). The local required() closure throws whenever a key is absent or empty, naming the missing key in the message. Each key is read via required() while assembling the resolved agentCoreProfile input.

Source

Thrown at server/src/services/native-runtime/provider-profile.ts:554

  if (profile.provider === "aws_agentcore") {
    const stored = input.agentCoreProfile;
    if (
      !stored
      || (
        profile.agentCoreProfileId !== stored.id
        && profile.agentCoreProfileId !== stored.profileKey
      )
    ) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_aws_agentcore_profile_mismatch",
        "The qualified AWS AgentCore profile does not match the adapter selection.",
      );
    }
    const remote = asRecord(stored.configuration);
    const required = (key: string): string => {
      const value = optionalString(remote[key]);
      if (!value) {
        throw new PaperclipRunnerProviderProfileError(
          "paperclip_runner_aws_agentcore_profile_invalid",
          `The qualified AWS AgentCore profile is missing ${key}.`,
        );
      }
      return value;
    };
    if (remote.eventExpiryDays !== 90) {
      throw new PaperclipRunnerProviderProfileError(
        "paperclip_runner_aws_agentcore_retention_unqualified",
        "The qualified AWS AgentCore profile must retain Memory events for exactly 90 days.",
      );
    }
    const maxEstimatedSessionCostUsd = profile.maxEstimatedSessionCostUsd
      ?? positiveNumberOrNull(
        remote.defaultMaxEstimatedSessionCostUsd,
        "paperclip_runner_aws_agentcore_spend_cap_invalid",
        "The AWS AgentCore profile requires a positive estimated session spend ceiling.",
      );

View on GitHub (pinned to 01ad858492)

Solutions

1. Read the message's ${key} to identify the missing field, then populate it in the stored profile configuration via the AgentCore profile service/API.
2. Re-run the AgentCore qualification flow so all resources (memory, endpoint, harness, context bucket/KMS) are provisioned and their identifiers saved.
3. If an AWS resource is genuinely missing (e.g. the KMS key or endpoint), recreate it and update configuration with the new ARN.
4. Compare the stored configuration object against the full required-key list in provider-profile.ts:585-599 and backfill every gap.

Example fix

// before (stored configuration)
{ "region": "us-east-1", "accountId": "111122223333", "memoryArn": "arn:..." }
// after (missing key added)
{ "region": "us-east-1", "accountId": "111122223333", "memoryArn": "arn:...", "memoryId": "mem-abc123", "contextKmsKeyArn": "arn:aws:kms:..." }

const REQUIRED_AGENTCORE_KEYS = ["region","accountId","harnessArn","harnessVersion","endpointArn","endpointQualifier","agentRuntimeArn","memoryArn","memoryId","invocationRoleArn","contextBucket","contextPrefix","contextKmsKeyArn","qualificationRevision","defaultModel"] as const;
const missing = REQUIRED_AGENTCORE_KEYS.filter(k => !storedProfile.configuration?.[k]);
if (missing.length) throw new Error(`AgentCore profile incomplete; missing: ${missing.join(", ")}`);

const hasAllAgentCoreKeys = (
  c: Record<string, unknown> | null | undefined,
): c is Record<(typeof REQUIRED_AGENTCORE_KEYS)[number], string> =>
  !!c && REQUIRED_AGENTCORE_KEYS.every(k => typeof c[k] === "string" && c[k].length > 0);

try {
  await executeRun(run);
} catch (e) {
  if (e instanceof PaperclipRunnerProviderProfileError && e.code === "paperclip_runner_aws_agentcore_profile_invalid") {
    const key = /missing (\w+)\.$/.exec(e.message)?.[1];
    throw new Error(`Re-run AgentCore qualification to populate configuration.${key}`);
  }
  throw e;
}

When it happens

Trigger: resolvePaperclipRunnerNativeProviderInput runs with provider=aws_agentcore and stored.configuration lacks one of the required keys — e.g. required('memoryId') or required('contextKmsKeyArn') finds undefined/empty string. The message interpolates the exact missing key, e.g. 'The qualified AWS AgentCore profile is missing memoryId.'

Common situations: A partially completed AgentCore qualification/provisioning flow that stored configuration before all resources were created; a CloudFormation/CDK stack failing mid-way so e.g. endpointArn never populated; manual JSON editing of the configuration column dropping a field; schema drift after an upgrade adds a new required key to old profiles.

Related errors

• paperclip_runner_aws_agentcore_profile_mismatch
• paperclip_runner_claude_managed_beta_unqualified
• paperclip_runner_claude_managed_model_invalid
• paperclip_runner_aws_agentcore_retention_unqualified
• paperclip_runner_aws_agentcore_spend_cap_invalid

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