Claude Managed live sessions require a qualified managed…

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.

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@3f1d897a7c (2026-09-02). Data as JSON: /api/errors/77d8eac5838ccf7a. Report an issue: GitHub.

Appendix: 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 3f1d897a7c)