What causes "Managed live sessions require an explicit qualified model" in paperclipai/paperclip?

Pass an explicit, non-empty input.requestedModel for managed providers

Managed live sessions require an explicit qualified model

Error message

Managed live sessions require an explicit qualified model

What it means

For both managed providers (claude_managed and aws_agentcore), create() demands an explicit non-empty requestedModel. Managed remote sessions must pin a qualified model; relying on defaults is rejected so the spend ceiling and qualification remain well-defined.

Source

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

    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"))
      : null;
    const capabilities = [...(input.capabilities ?? [])];
    const scenario = input.scenario ?? { id: "capability-live-default" };
    const authority: CapabilityLiveAuthoritySnapshot = {
      active: true,
      runId,
      companyId: input.companyId ?? state.company.id,
      actorId: input.actorId ?? state.actors[0]!.id,
      taskId: input.taskId ?? state.tasks[0]!.id,

View on GitHub (pinned to 01ad858492)

Solutions

Pass an explicit, non-empty input.requestedModel for managed providers
Trim/validate the model string before calling create()
Fix config loading so an unset model fails at config time with a clearer message
Pick a qualified model from the profile's allowed model list

Example fix

// before
await liveSession.create({ provider: 'claude_managed', managedProfile, requestedModel: env.MODEL }); // '' if unset
// after
const model = env.MODEL?.trim();
if (!model) throw new Error('MODEL env var required for managed sessions');
await liveSession.create({ provider: 'claude_managed', managedProfile, requestedModel: model });

Defensive patterns

Strategy: validation

Validate before calling

if ((provider === 'claude_managed' || provider === 'aws_agentcore') && !requestedModel?.trim()) throw new Error('requestedModel required for managed providers');

Try / catch

try {
  await liveSession.create(input);
} catch (err) {
  if (err instanceof Error && err.message.includes('explicit qualified model')) {
    // prompt operator to pick a model
  } else throw err;
}

Prevention

Always set requestedModel explicitly for managed providers
Trim and check non-empty before create()
Fail at config parse time when the model value is blank

When it happens

Trigger: Calling create({ provider: 'claude_managed' | 'aws_agentcore', ... }) with requestedModel missing, empty string, or whitespace-only.

Common situations: Model left to a default that turns out empty; config value read from unset env var yielding ''; user cleared the model field in settings.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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