{"record":{"id":"3537f194a2f1f3bc","repo":"microsoft/typescript-go","slug":"errclienterror","errorCode":"ErrClientError","errorMessage":"api: client error","messagePattern":"api: client error","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/api/proto.go","lineNumber":25,"sourceCode":"\t\"github.com/microsoft/typescript-go/internal/ast\"\n\t\"github.com/microsoft/typescript-go/internal/checker\"\n\t\"github.com/microsoft/typescript-go/internal/collections\"\n\t\"github.com/microsoft/typescript-go/internal/core\"\n\t\"github.com/microsoft/typescript-go/internal/diagnostics\"\n\t\"github.com/microsoft/typescript-go/internal/jsnum\"\n\t\"github.com/microsoft/typescript-go/internal/json\"\n\t\"github.com/microsoft/typescript-go/internal/locale\"\n\t\"github.com/microsoft/typescript-go/internal/ls/lsconv\"\n\t\"github.com/microsoft/typescript-go/internal/lsp/lsproto\"\n\t\"github.com/microsoft/typescript-go/internal/packagejson\"\n\t\"github.com/microsoft/typescript-go/internal/project\"\n\t\"github.com/microsoft/typescript-go/internal/tsoptions\"\n\t\"github.com/microsoft/typescript-go/internal/tspath\"\n)\n\nvar (\n\tErrInvalidRequest = errors.New(\"api: invalid request\")\n\tErrClientError    = errors.New(\"api: client error\")\n)\n\ntype Method string\n\ntype (\n\tSnapshotID  uint64\n\tProjectID   string\n\tSymbolID    uint64\n\tTypeID      uint32\n\tSignatureID uint64\n\tNodeHandle  string\n)\n\nfunc ProjectHandle(p *project.Project) ProjectID {\n\treturn ProjectID(p.ID())\n}\n\nfunc SymbolHandle(symbol *ast.Symbol) SymbolID {","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/microsoft/typescript-go/blob/1bcfa18d79a3be41772223d5c05dfe4480e614ff/internal/api/proto.go#L7-L43","documentation":"Sentinel error wrapped by dozens of session-level failures caused by the client's view being stale rather than the request being malformed: unknown snapshot/symbol/type/signature/node handles, project not found, project without a program, source file not found, unreadable config. errors.Is(err, api.ErrClientError) means: refresh your state and retry, do not blame the payload shape.","triggerScenarios":"Using a SnapshotID after the server invalidated it; passing a NodeHandle from an older snapshot; requesting a file not loaded in the project; asking about a project before its program is built; a handle registry miss after project reload.","commonSituations":"Long-lived editor sessions where documents change under cached IDs; reconnecting without re-initializing; racing project load; deleting files without notifying the server.","solutions":["Re-acquire current IDs (open a fresh snapshot) and retry the request","Send filesChanged/open/close notifications so server snapshots track your edits","Wait for project/program readiness before issuing dependent calls","For deleted files, notify the deletion so the server stops holding handles into them"],"exampleFix":"// before\nres, err := session.GetDiagnostics(ctx, oldSnapshotID, file)\n\n// after\nif errors.Is(err, api.ErrClientError) {\n\tsnap, _ := session.OpenSnapshot(ctx, file)\n\tres, err = session.GetDiagnostics(ctx, snap.ID, file)\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":"func isClientError(err error) bool { return errors.Is(err, api.ErrClientError) }","tryCatchPattern":"res, err := session.Something(ctx, params)\nif errors.Is(err, api.ErrClientError) {\n\t// stale handles / unknown project / missing file: refresh state and retry once\n\tsnap, rerr := session.Refresh(ctx)\n\tif rerr == nil {\n\t\tres, err = session.Something(ctx, params)\n\t}\n}\nreturn res, err","preventionTips":["Re-acquire snapshot/handle IDs after every file change","Send filesChanged notifications so the server tracks edits","Wait for project load before issuing dependent requests","Treat ErrClientError as retriable-with-refresh, never as a payload bug"],"tags":["go","sentinel","stale-handle","session","retry","snapshot"],"backgroundTag":null,"analyzedSha":"1bcfa18d79a3be41772223d5c05dfe4480e614ff","analyzedAt":"2026-08-16T02:12:00.115Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}