ACP prompt stopped before completing: ${response.stopReason}

Error message

ACP prompt stopped before completing: ${response.stopReason}

What it means

Same as error 2580 but in the restore-version handler: it requires a configured storage adapter before it can read or write agent versions. mastra.getStorage() returning undefined produces this 500 HTTPException.

Source

Thrown at agent-sdks/acp/src/connection.ts:345

      },
      ...this.options.initialize,
    };
  }

  private getNewSessionRequest(): NewSessionRequest {
    return {
      cwd: this.options.cwd ?? process.cwd(),
      mcpServers: [],
      ...this.options.session,
    };
  }

  private throwIfPromptDidNotComplete(response: PromptResponse): void {
    if (response.stopReason === 'end_turn') {
      return;
    }

    throw new Error(`ACP prompt stopped before completing: ${response.stopReason}`);
  }

  private withStderr(error: unknown): Error {
    const stderr = this.stderr.trim();

    if (error instanceof Error) {
      if (stderr && !error.message.includes(stderr)) {
        error.message = `${error.message}\n\nACP agent stderr:\n${stderr}`;
      }

      return error;
    }

    return new Error(stderr ? `${String(error)}\n\nACP agent stderr:\n${stderr}` : String(error));
  }
}

type AsyncQueue<T> = AsyncIterable<T> & {

View on GitHub (pinned to 75dd419e61)

Solutions

Add storage: new PostgresStore({...}) (or equivalent) to the Mastra instance options
Ensure the server hosting these handlers uses the Mastra instance that includes storage
Check env vars used to build the storage connection (DATABASE_URL etc.) so config isn't silently skipped
Redeploy after fixing config

Example fix

// before
const mastra = new Mastra({ agents });
// after
const mastra = new Mastra({ agents, storage: new PostgresStore({ connectionString: process.env.DATABASE_URL }) });

Defensive patterns

Strategy: try-catch

Validate before calling

const mastra = getMastra();
if (!mastra?.getStorage?.()) throw new Error('Cannot restore agent version: storage not configured');

Type guard

function storageReady(m: unknown): m is { getStorage: () => object } {
  return !!m && typeof (m as any).getStorage === 'function' && !!(m as any).getStorage();
}

Try / catch

try {
  await fetch(`/api/agents/${agentId}/versions/${versionId}/restore`, { method: 'POST' });
} catch (e) {
  if (isHttpError(e) && e.status === 500 && /Storage is not configured/.test(e.message)) {
    // add storage to Mastra config, redeploy, retry
  } else throw e;
}

Prevention

Configure storage before enabling version/restore features
Assert storage presence at server startup
Keep storage wiring in shared config used by all server entrypoints
Test restore endpoints in CI against a storage-backed instance

When it happens

Trigger: POST (restore) on /api/agents/:agentId/versions/:versionId against a Mastra instance without `storage` configured.

Common situations: Dev instances built without persistence; storage omitted from server/mastra config after refactoring; environment gating that disables storage in the deployed build.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/583edec0cb383adb. Report an issue: GitHub.