paperclipai/paperclip · error · HttpError

ambiguous_workspace_path

ambiguous_workspace_path

Error message

Workspace path matched multiple project workspaces

What it means

Auto-discovery ambiguity result: when scanning the issue's same-company project workspaces for a target (path/candidate), more than one workspace matched, so Paperclip cannot safely pick one. The ambiguous state surfaces as an error asking the caller to disambiguate with an explicit projectId/workspaceId target.

Source

Thrown at server/src/services/workspace-file-resources.ts:1228

  ): Promise<AutoDiscovered<T>> {
    const candidates = await sameCompanyProjectWorkspaceCandidates(issue, excludedWorkspaceIds);
    const matches: T[] = [];
    for (const candidate of candidates) {
      if (candidate.remote) continue;
      try {
        matches.push(await check(candidate));
      } catch (error) {
        if (isHttpStatus(error, 404)) continue;
        throw error;
      }
      if (matches.length > 1) return { state: "ambiguous", count: matches.length };
    }
    if (matches.length === 1) return { state: "one", value: matches[0]! };
    return { state: "none" };
  }

  function throwAmbiguousWorkspacePath(count: number): never {
    throw new HttpError(409, "Workspace path matched multiple project workspaces", {
      code: "ambiguous_workspace_path",
      matchCount: count,
    });
  }

  async function availability(
    issueId: string,
    input: WorkspaceFileAvailabilityRequestInput,
    opts: { issue?: IssueRow } = {},
  ): Promise<WorkspaceFileAvailabilityResponse> {
    const issue = opts.issue ?? await getIssue(issueId);
    const uniqueQueries = new Map<string, PreparedAvailabilityQuery>();
    for (const inputQuery of input.queries) {
      const prepared = prepareAvailabilityQuery(inputQuery);
      if (!uniqueQueries.has(prepared.key)) uniqueQueries.set(prepared.key, prepared);
    }
    const queries = [...uniqueQueries.values()];
    if (queries.length === 0) return { kind: "workspace_file_availability", results: [] };

View on GitHub (pinned to 120ae5428f)

Solutions

1. The path maps to more than one project workspace. Disambiguate by specifying the project or using a more specific path.

When it happens

Trigger: Thrown at server/src/services/workspace-file-resources.ts:1228 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/0ce6bff38e21b6a2. Report an issue: GitHub.