{"record":{"id":"11d84c6f049e204d","repo":"can1357/oh-my-pi","slug":"symbol-is-required-for-project-aware-action-pa","errorCode":null,"errorMessage":"symbol is required for project-aware ${action}; pass symbol=<name>, optionally symbol#N for repeated occurrences","messagePattern":"symbol is required for project-aware (.+?); pass symbol=<name>, optionally symbol#N for repeated occurrences","errorType":"exception","errorClass":"ToolError","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/lsp/tool.ts","lineNumber":1183,"sourceCode":"\t\t\t\tawait ensureFileOpen(client, targetFile, signal);\n\t\t\t}\n\t\t\tif (rustWorkspaceWait) {\n\t\t\t\tawait waitForProjectLoaded(client, signal);\n\t\t\t}\n\n\t\t\t// For project-aware servers, references/rename/definition without a `symbol`\n\t\t\t// silently falls back to the first non-whitespace column on the line, which\n\t\t\t// frequently points at the wrong identifier (decorator, keyword, parameter)\n\t\t\t// and the server returns plausible-looking but unrelated results. Require\n\t\t\t// `symbol` explicitly so callers cannot accidentally trigger that fallback.\n\t\t\tif (\n\t\t\t\ttargetFile &&\n\t\t\t\tline !== undefined &&\n\t\t\t\t!symbol &&\n\t\t\t\t(action === \"references\" || action === \"rename\" || action === \"definition\") &&\n\t\t\t\tisProjectAwareLspServer(serverConfig)\n\t\t\t) {\n\t\t\t\tthrow new ToolError(\n\t\t\t\t\t`symbol is required for project-aware ${action}; pass symbol=<name>, optionally symbol#N for repeated occurrences`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst uri = targetFile ? fileToUri(targetFile) : \"\";\n\t\t\tconst resolvedLine = line ?? 1;\n\t\t\tconst resolvedCharacter = targetFile ? await resolveSymbolColumn(targetFile, resolvedLine, symbol) : 0;\n\t\t\tconst position = { line: resolvedLine - 1, character: resolvedCharacter };\n\n\t\t\tlet output: string;\n\t\t\t// Set on bare empty-lookup outcomes (no definition/references/…): the\n\t\t\t// result carries no information once consumed, so compaction may elide\n\t\t\t// it. Clean diagnostics runs are NOT useless — they are verification\n\t\t\t// evidence.\n\t\t\tlet useless = false;\n\n\t\t\tif (needsProjectIndex && !isRustAnalyzerServer) {\n\t\t\t\tawait waitForProjectLoaded(client, signal);\n\t\t\t}","sourceCodeStart":1165,"sourceCodeEnd":1201,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/lsp/tool.ts#L1165-L1201","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the `symbol` parameter to the call: `{action:\"references\", file:\"src/a.ts\", line:10, symbol:\"myFunc\"}`.","Use `symbol#N` when the name appears multiple times on the line to pick the occurrence (1-based).","Alternatively target the exact character position in a way the server supports, or use a non-project-aware server config for positional lookups.","Update prompt/agent templates for project-aware servers to always include the symbol."],"exampleFix":"// before\nawait lspTool.execute({ action: \"references\", file: \"src/a.ts\", line: 10 });\n// after\nawait lspTool.execute({ action: \"references\", file: \"src/a.ts\", line: 10, symbol: \"myFunc\" });","handlingStrategy":"validation","validationCode":"if ([\"references\",\"rename\",\"definition\"].includes(params.action) && isProjectAwareLspServer(serverConfig) && !params.symbol) {\n  throw new Error(\"symbol parameter required for this server type\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  await lspTool.execute({ action: \"references\", file, line });\n} catch (err) {\n  if (err instanceof ToolError && err.message.includes(\"symbol is required\")) {\n    return lspTool.execute({ action: \"references\", file, line, symbol: symbolAt(file, line) });\n  } throw err;\n}","preventionTips":["Always include `symbol` (and `#N` when ambiguous) for references/rename/definition calls.","Update tool-call templates when switching to project-aware servers.","Derive the symbol from the source line before issuing the call."],"tags":["lsp","validation","parameters","tool"],"backgroundTag":"missing-required-parameter","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}