paperclipai/paperclip · error

native_session_goal_unavailable

native_session_goal_unavailable

Error message

native_session_goal_unavailable

What it means

goal forwards a goal-setting call to the HarnessSession's optional goal capability. When the driver does not implement goal, the backend throws native_session_goal_unavailable because the session cannot accept programmatic goal updates. Protocol integrity is asserted before and after the delegation.

Source

Thrown at packages/paperclip-runner/src/backends/harness-driver-backend.ts:746

  }

  handoffRuntimeRequest(input: {
    requestId: string;
    turnId: string;
    reason: "durable_handoff";
    signal: AbortSignal;
  }) {
    this.#assertProtocolIntegrity();
    if (this.#session.handoffRuntimeRequest === undefined) {
      throw new Error("native_runtime_request_handoff_unavailable");
    }
    return this.#session.handoffRuntimeRequest(input);
  }

  goal(input: Parameters<NonNullable<HarnessSession["goal"]>>[0]) {
    this.#assertProtocolIntegrity();
    if (this.#session.goal === undefined) {
      throw new Error("native_session_goal_unavailable");
    }
    return this.#withProtocolIntegrity(() => this.#session.goal!(input));
  }

  async result() {
    this.#assertProtocolIntegrity();
    if (this.#explicitlyCancelled) return null;
    const snapshot = await this.#harnessSnapshot();
    if (
      snapshot.semanticResult === undefined ||
      snapshot.semanticResult === null
    ) {
      return null;
    }
    if (this.#terminal === null) {
      return null;
    }
    return {

View on GitHub (pinned to 01ad858492)

Solutions

1. Upgrade the driver/adapter to a version implementing goal
2. Pass the goal at session creation time instead of updating it dynamically
3. Guard with a capability check and disable goal editing in the UI for unsupported agents
4. Recreate the session with the new goal if dynamic updates are unsupported

Example fix

// before
await backend.goal({ text: newGoal });
// after
if (!backend.canSetGoal()) {
  await recreateSessionWithGoal(newGoal);
} else {
  await backend.goal({ text: newGoal });
}

if (typeof session.goal !== 'function') throw new Error('goal updates unsupported by driver');

const canSetGoal = (s: HarnessSession): s is HarnessSession & { goal: NonNullable<HarnessSession['goal']> } => typeof s.goal === 'function';

try { await backend.goal(input); } catch (e) { if (e.message === 'native_session_goal_unavailable') { await recreateSessionWithGoal(input); } else throw e; }

When it happens

Trigger: Calling goal() on a session whose driver has no goal method (this.#session.goal === undefined); setting or updating a run goal on a driver lacking the goal protocol extension.

Common situations: Board-driven goal updates targeting an agent adapter without goal support; older driver builds predating the goal method; drivers where goals are supplied only at session creation, not dynamically.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• native_session_multi_run_unavailable
• steering is unavailable
• native_session_attach_binding_mismatch
• interruption is unavailable
• native_runtime_request_resolution_unavailable

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