can1357/oh-my-pi · error · ToolError

symbol is required for project-aware ${action}; pass symbol=

Error message

symbol is required for project-aware ${action}; pass symbol=<name>, optionally symbol#N for repeated occurrences

What it means

Project-aware LSP servers index symbols project-wide, so position-based calls for references/rename/definition would be ambiguous. The tool requires an explicit `symbol` parameter (optionally `symbol#N` for repeated occurrences) when such a server is selected and only a file+line is given.

Source

Thrown at packages/coding-agent/src/lsp/tool.ts:1183

				await ensureFileOpen(client, targetFile, signal);
			}
			if (rustWorkspaceWait) {
				await waitForProjectLoaded(client, signal);
			}

			// For project-aware servers, references/rename/definition without a `symbol`
			// silently falls back to the first non-whitespace column on the line, which
			// frequently points at the wrong identifier (decorator, keyword, parameter)
			// and the server returns plausible-looking but unrelated results. Require
			// `symbol` explicitly so callers cannot accidentally trigger that fallback.
			if (
				targetFile &&
				line !== undefined &&
				!symbol &&
				(action === "references" || action === "rename" || action === "definition") &&
				isProjectAwareLspServer(serverConfig)
			) {
				throw new ToolError(
					`symbol is required for project-aware ${action}; pass symbol=<name>, optionally symbol#N for repeated occurrences`,
				);
			}
			const uri = targetFile ? fileToUri(targetFile) : "";
			const resolvedLine = line ?? 1;
			const resolvedCharacter = targetFile ? await resolveSymbolColumn(targetFile, resolvedLine, symbol) : 0;
			const position = { line: resolvedLine - 1, character: resolvedCharacter };

			let output: string;
			// Set on bare empty-lookup outcomes (no definition/references/…): the
			// result carries no information once consumed, so compaction may elide
			// it. Clean diagnostics runs are NOT useless — they are verification
			// evidence.
			let useless = false;

			if (needsProjectIndex && !isRustAnalyzerServer) {
				await waitForProjectLoaded(client, signal);
			}

View on GitHub (pinned to 9690622007)

Solutions

1. Add the `symbol` parameter to the call: `{action:"references", file:"src/a.ts", line:10, symbol:"myFunc"}`.
2. Use `symbol#N` when the name appears multiple times on the line to pick the occurrence (1-based).
3. Alternatively target the exact character position in a way the server supports, or use a non-project-aware server config for positional lookups.
4. Update prompt/agent templates for project-aware servers to always include the symbol.

Example fix

// before
await lspTool.execute({ action: "references", file: "src/a.ts", line: 10 });
// after
await lspTool.execute({ action: "references", file: "src/a.ts", line: 10, symbol: "myFunc" });

if (["references","rename","definition"].includes(params.action) && isProjectAwareLspServer(serverConfig) && !params.symbol) {
  throw new Error("symbol parameter required for this server type");
}

try {
  await lspTool.execute({ action: "references", file, line });
} catch (err) {
  if (err instanceof ToolError && err.message.includes("symbol is required")) {
    return lspTool.execute({ action: "references", file, line, symbol: symbolAt(file, line) });
  } throw err;
}

When it happens

Trigger: execute() with action references/rename/definition, a target file and line, no `symbol` param, and isProjectAwareLspServer(serverConfig) true — e.g. calling `{action:"references", file:"src/a.ts", line:10}` against a project-aware server.

Common situations: Automated tool calls built from file:line pairs (editor integrations, agent prompts) that worked with positional servers but fail after switching to a project-aware server; prompts that omit the symbol argument.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Symbol "${symbol}" occurrence ${occurrence} is out of bounds
• LSP action ${action} is disabled in this read-only session
• LSP ${action} timed out after ${timeoutSec}s on ${serverName
• Symbol "${symbol}" not found on line ${lineNumber}
• File not found: ${filePath}

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/11d84c6f049e204d. Report an issue: GitHub.