Symbol and edit resolution errors

These codes mean the server understood your request but could not pin it to exactly one target. The fix is almost always to narrow or correct the request, not to retry it unchanged.

SYMBOL_NOT_FOUND

No indexed symbol matches the name (and file, if given). Causes in rough order of likelihood: a typo or wrong casing; the symbol lives in a file the index has not caught up with; the name is a concept, not a symbol name.

Recover: search_code with a shorter fragment to find the real name; if the file was just edited, refresh_index for it and retry; for concept-shaped lookups use list_files(fuzzy=...) then get_file_outline.

FILE_NOT_FOUND / NOT_FOUND

The path (or target) does not exist in the indexed state being queried. Check the path with list_files; if the file is brand new or just moved, refresh_index for it first.

MULTIPLE_MATCHES / AMBIGUOUS_MATCH

The name resolves to more than one symbol and the server will not guess. The response lists the candidates.

Recover: repeat the call with file_path (and kind/language where the tool accepts them) to pin exactly one.

AMBIGUOUS_ANCHOR / OLD_TEXT_MISMATCH

old_text-anchored editing requires the anchor to match the current bytes exactly and uniquely. OLD_TEXT_MISMATCH means it matched nothing — usually whitespace drift or an edit computed against older bytes. AMBIGUOUS_ANCHOR means it matched more than once.

Recover: re-read the exact range (get_lines), copy the bytes verbatim into old_text, and widen the snippet until it is unique.

DUPLICATE_SYMBOL / DUPLICATE_SYMBOL_CROSS_FILE

The write would create a symbol whose name already exists — in the same file, or elsewhere in the repository. cix refuses so the repo does not end up with two competing definitions.

Recover: call search_code for the name, read the existing definition, and either reuse it, extend it, or choose a distinct name.

INVALID_SOURCE_BYTES

The source you supplied could not be parsed well enough to index as a symbol — typically a syntax error or a fragment that is not a complete definition.

Recover: fix the snippet so it parses as a complete top-level definition and retry.

MISSING_ARGUMENT / MUTUALLY_EXCLUSIVE_ARGS / INVALID_ARGUMENT

Request-shape errors: a required field is absent, two fields that cannot be combined were both set, or a value fails validation. The message names the offending field. Correct the call; do not retry it verbatim.

INTERNAL_ERROR

The server hit an unexpected failure that is not your request's fault. Retry once; if it persists, note the tool and arguments and report it — this code is a defect signal, not a usage error.