{"record":{"id":"9d24886af718f061","repo":"qax-os/excelize","slug":"invalid-reference","errorCode":null,"errorMessage":"invalid reference","messagePattern":"invalid reference","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"calc.go","lineNumber":1631,"sourceCode":"\t\t}\n\t\treturn cr, false, false, err\n\t}\n\treturn cr, false, false, err\n}\n\n// prepareCellRange checking and convert cell reference to a cell range.\nfunc (cr *cellRange) prepareCellRange(col, row bool, cellRef cellRef) error {\n\tif col {\n\t\tcellRef.Row = TotalRows\n\t}\n\tif row {\n\t\tcellRef.Col = MaxColumns\n\t}\n\tif cellRef.Sheet == \"\" {\n\t\tcellRef.Sheet = cr.From.Sheet\n\t}\n\tif cr.From.Sheet != cellRef.Sheet || cr.To.Sheet != cellRef.Sheet {\n\t\treturn errors.New(\"invalid reference\")\n\t}\n\tif cr.From.Col > cellRef.Col {\n\t\tcr.From.Col = cellRef.Col\n\t}\n\tif cr.From.Row > cellRef.Row {\n\t\tcr.From.Row = cellRef.Row\n\t}\n\tif cr.To.Col < cellRef.Col {\n\t\tcr.To.Col = cellRef.Col\n\t}\n\tif cr.To.Row < cellRef.Row {\n\t\tcr.To.Row = cellRef.Row\n\t}\n\treturn nil\n}\n\n// parseReference parse reference and extract values by given reference\n// characters and default sheet name.","sourceCodeStart":1613,"sourceCodeEnd":1649,"githubUrl":"https://github.com/qax-os/excelize/blob/f2483381fbfbe432a6baa98d48a1c277183f3285/calc.go#L1613-L1649","documentation":"During range/reference normalization, the code adjusts a cellRange against parsed bounds and requires that both the From and To endpoints belong to the same sheet as the parsed cell reference. If they differ, it returns errors.New(\"invalid reference\"). This is a plain Go error (no Excel error code), raised for cross-sheet or malformed ranges where one endpoint's sheet does not match.","triggerScenarios":"Calling APIs that resolve ranges (formula evaluation involving A1:B2 style references, e.g. via GetCellValue-driven formula recalculation or parseReference paths) where the range endpoints reference different sheets, like Sheet1!A1:Sheet2!B2, or where the From.Sheet was not set as expected.","commonSituations":"3-D or cross-sheet range formulas (Sheet1:Sheet3!A1) that excelize does not support; programmatically constructed cellRange structs with inconsistent Sheet fields; copied formulas whose sheet qualifier was lost.","solutions":["Rewrite the formula so both range endpoints are on the same sheet","Explicitly qualify the sheet consistently, e.g. Sheet1!A1:Sheet1!B2","If constructing cellRef/cellRange in code, set Sheet identically on From and To","Split cross-sheet computations into separate same-sheet formulas or handle them in Go code"],"exampleFix":"// before: formula =SUM(Sheet1!A1:Sheet2!B2) -> invalid reference\n// after: =SUM(Sheet1!A1:Sheet1!B2) plus a separate =SUM(Sheet2!A1:Sheet2!B2)","handlingStrategy":"validation","validationCode":"// ensure range endpoints share one sheet before evaluating\n// reject cross-sheet ranges like Sheet1!A1:Sheet2!B2\nif strings.Count(formula, \"!\") > 1 && strings.Contains(formula, \":\") {\n    return fmt.Errorf(\"cross-sheet range not supported\")\n}","typeGuard":null,"tryCatchPattern":"if _, err := f.Calculate(); err != nil {\n    if err.Error() == \"invalid reference\" {\n        // rewrite formula with consistent sheet qualification\n    }\n    return err\n}","preventionTips":["Qualify both range endpoints with the same sheet name","Avoid 3-D references (Sheet1:Sheet3!A1) which excelize does not support","When building cellRange structs in Go, set Sheet identically on From and To"],"tags":["excel","formula","reference","range"],"backgroundTag":"invalid-cell-reference","analyzedSha":"f2483381fbfbe432a6baa98d48a1c277183f3285","analyzedAt":"2026-09-02T01:26:19.299Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}