OpenHands/OpenHands · warning · Error

Branching a conversation isn't supported on the cloud backen

Error message

Branching a conversation isn't supported on the cloud backend yet.

What it means

Thrown by forkConversation when the active backend is cloud. Conversation forking/branching (POST /fork with from_event_id) is a local agent-server feature only — the cloud backend's app-server does not implement the fork endpoint. This is a deliberate feature gap, not a bug; the error message is user-facing.

Source

Thrown at src/api/conversation-service/agent-server-conversation-service.api.ts:773

    });
    const [conversation] = await this.batchGetAppConversations([
      conversationId,
    ]);
    return requireAppConversation(conversation, conversationId);
  }

  /**
   * Forks a conversation, copying event history up to and including
   * `fromEventId`. Local agent-server only; needs agent-server >= 1.31.0 for
   * `from_event_id` (older backends copy the whole conversation).
   */
  static async forkConversation(
    sourceConversationId: string,
    fromEventId: string,
    title?: string,
  ): Promise<DirectConversationInfo> {
    if (getActiveBackend().backend.kind === "cloud") {
      throw new Error(
        "Branching a conversation isn't supported on the cloud backend yet.",
      );
    }

    // `from_event_id` is accepted by `/fork` but not yet typed in
    // ForkConversationRequest (through client 1.32.0); the client forwards the
    // body verbatim, so cast to carry it. A title also suppresses the backend
    // auto-title, so the "(branch)" marker sticks.
    const data = await new ConversationClient(
      getAgentServerClientOptions(),
    ).forkConversation<DirectConversationInfo>(sourceConversationId, {
      from_event_id: fromEventId,
      ...(title ? { title } : {}),
    } as ForkConversationRequest & { from_event_id: string });

    // Carry over the source's client-side metadata (repo/branch/workspace/
    // profile/plugins) so the fork hydrates its chat-page badges the same way.
    const sourceMetadata = getStoredConversationMetadata(sourceConversationId);

View on GitHub (pinned to 500b4c533e)

Solutions

1. Hide or disable the 'Branch from here' UI control when the active backend is cloud.
2. Show a tooltip explaining branching is not yet available on cloud when the control is visible but disabled.
3. If branching support is needed on cloud, implement it via the cloud app-server API (requires backend work beyond the frontend).

Example fix

// before: branch button always shown
<Button onClick={() => forkConversation(id, eventId)}>Branch from here</Button>

// after: hide for cloud
{getActiveBackend().backend.kind === 'local' && (
  <Button onClick={() => forkConversation(id, eventId)}>Branch from here</Button>
)}

import { getActiveBackend } from '#/api/backend-registry/active-store';

function canForkConversation(): boolean {
  return getActiveBackend().backend.kind === 'local';
}

// Before showing branch UI:
if (!canForkConversation()) {
  hideBranchButton(); // or show with disabled + tooltip
}

function isForkNotSupported(e: unknown): boolean {
  return e instanceof Error && e.message.includes("isn't supported on the cloud backend");
}

try {
  await AgentServerConversationService.forkConversation(sourceId, eventId, title);
} catch (error) {
  if (error instanceof Error && error.message.includes('cloud backend')) {
    showToast('Branching is not available on cloud yet');
    return;
  }
  throw error;
}

When it happens

Trigger: AgentServerConversationService.forkConversation(sourceId, eventId, title) is called when getActiveBackend().backend.kind is 'cloud'. The UI branch action triggers this code path on a cloud conversation.

Common situations: User clicks 'Branch from here' on a cloud conversation; the branch UI control is not properly hidden for cloud backends; user switched from local to cloud with a branch action queued.

Related errors

• Public sharing requires a cloud backend.
• Conversation sandbox is still starting. Wait for it to finis
• Conversation sandbox is still starting. Wait for it to finis
• Invalid response from runtime - runtime may be unavailable
• OAuth authorization requires a reachable local backend.

AI-assisted analysis of OpenHands/OpenHands@500b4c533e (2026-08-12). Data as JSON: /api/errors/694ff63dd3ed4498. Report an issue: GitHub.