Claude Managed live sessions require a qualified managed pro

Error message

Claude Managed live sessions require a qualified managed profile

What it means

CapabilityLiveSession.create validates that claude_managed provider sessions carry a managedProfile describing the qualified managed setup. Missing it means the runner has no profile to drive the managed Claude session, so it throws before creating any session state.

Source

Thrown at packages/paperclip-runner/src/live/live-session.ts:868

  readonly #store: CapabilityLiveSessionStore;
  readonly #transportFactory: CapabilityLiveTransportFactory;
  readonly #transportOptions: CapabilityRunnerdCodexTransportOptions;
  readonly #now: () => Date;
  readonly #sessions = new Map<string, CapabilityLiveSession>();

  constructor(options: CapabilityLiveSessionServiceOptions = {}) {
    this.#store = options.store ?? new InMemoryCapabilityLiveSessionStore();
    this.#transportFactory = options.transportFactory ?? createCapabilityRunnerdCodexTransport;
    this.#transportOptions = options.transportOptions ?? {};
    this.#now = options.now ?? (() => new Date());
  }

  async create(input: CreateCapabilityLiveSessionInput = {}): Promise<CapabilityLiveSession> {
    if (input.provider === "acpx" && input.acpxAgent === "pi") {
      throw new Error("The Pi ACPX profile is not available");
    }
    if (input.provider === "claude_managed" && !input.managedProfile) {
      throw new Error("Claude Managed live sessions require a qualified managed profile");
    }
    if (input.provider === "aws_agentcore" && !input.agentCoreProfile) {
      throw new Error("AWS AgentCore live sessions require a qualified AgentCore profile");
    }
    if (
      (input.provider === "claude_managed" || input.provider === "aws_agentcore") &&
      !input.requestedModel?.trim()
    ) {
      throw new Error("Managed live sessions require an explicit qualified model");
    }
    const port = new CapabilityMockControlPlaneAdapter(input.seed);
    const seedState = port.serialize();
    await port.start();
    const state = port.snapshot();
    const sessionId = input.sessionId ?? randomUUID();
    const runId = input.runId ?? randomUUID();
    const acpxProfile = input.provider === "acpx"
      ? resolveQualifiedAcpxProfile(input.acpxAgent ?? "codex", requireNonEmpty(input.requestedModel ?? "", "requested_model"))

View on GitHub (pinned to 01ad858492)

Solutions

Pass a valid input.managedProfile object when using provider 'claude_managed'
Fix config loading so the managed profile (credentials, model ceiling, etc.) is populated before create()
Validate the profile exists before constructing the create() input
Use a non-managed provider if a managed profile is genuinely not available

Example fix

// before
await liveSession.create({ provider: 'claude_managed' });
// after
if (!managedProfile) throw new Error('configure managedProfile for claude_managed');
await liveSession.create({ provider: 'claude_managed', managedProfile });

Defensive patterns

Strategy: validation

Validate before calling

if (input.provider === 'claude_managed' && !input.managedProfile) throw new Error('managedProfile required for claude_managed sessions');

Type guard

function hasManagedProfile(input: { provider: string; managedProfile?: object }): input is { provider: 'claude_managed'; managedProfile: object } {
  return input.provider === 'claude_managed' && !!input.managedProfile;
}

Try / catch

try {
  await liveSession.create(input);
} catch (err) {
  if (err instanceof Error && err.message.includes('require a qualified managed profile')) {
    // surface config error to operator
  } else throw err;
}

Prevention

Validate provider-specific required fields before create()
Load and verify managed profiles during config init
Use typed input builders that require the profile per provider

When it happens

Trigger: Calling create({ provider: 'claude_managed' }) without input.managedProfile, or with managedProfile set to undefined/null (e.g. from incomplete config).

Common situations: Config loading omits the managed profile section; copying an example that used the default provider; switching provider to claude_managed without adding profile credentials/settings.

Related errors

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