chenhg5/cc-connect · error

cannot parse local reference

Error message

cannot parse local reference

What it means

After stripping a markdown-link wrapper, `parseUserLocalReference` delegates to `parseLocalReference`; if that returns `ok == false` the input matched no accepted local-reference form, so it fails with `cannot parse local reference`. The library only accepts workspace-relative paths (optionally with :line suffixes) and plain/markdown-link forms.

Source

Thrown at core/reference_parse.go:66

	reColonLineRange = regexp.MustCompile(`^(.*):(\d+)-(\d+)$`)
	reColonLineOnly  = regexp.MustCompile(`^(.*):(\d+)$`)
)

func parseUserLocalReference(raw, workspaceDir string) (*localReference, error) {
	raw = strings.TrimSpace(raw)
	if raw == "" {
		return nil, fmt.Errorf("empty reference")
	}
	if match := reMarkdownLink.FindStringSubmatch(raw); len(match) >= 3 && match[0] == raw {
		suffix := ""
		if len(match) >= 4 {
			suffix = match[3]
		}
		raw = match[2] + suffix
	}
	ref, ok := parseLocalReference(raw, workspaceDir)
	if !ok {
		return nil, fmt.Errorf("cannot parse local reference")
	}
	return ref, nil
}

func parseLocalReference(raw, workspaceDir string) (*localReference, bool) {
	raw = strings.TrimSpace(raw)
	if raw == "" || isWebURL(raw) || strings.HasPrefix(raw, "//") {
		return nil, false
	}
	ref := &localReference{raw: raw}
	pathPart := raw
	switch {
	case reHashLocation.MatchString(pathPart):
		m := reHashLocation.FindStringSubmatch(pathPart)
		pathPart = m[1]
		ref.lineStart = atoiSafe(m[3])
		ref.column = atoiSafe(m[4])
		if ref.column > 0 {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Pass a plain workspace-relative path that exists (e.g. `core/engine.go` or `core/engine.go:42`).
2. Verify the file exists: `os.Stat(filepath.Join(workspaceDir, raw))` before calling.
3. If referencing a file outside workspaceDir, either move/symlink it into the workspace or use the supported reference form.
4. Convert external URLs/attachments to a downloaded local file path first, then reference that path.

Example fix

// before
req, err := buildReferenceViewRequest("https://example.com/foo.go", workspaceDir)

// after
p := "foo.go" // after downloading the remote file into the workspace
if _, err := os.Stat(filepath.Join(workspaceDir, p)); err != nil {
    reply("file not found in workspace: " + p)
    return
}
req, err := buildReferenceViewRequest(p, workspaceDir)

func referenceExists(raw, workspaceDir string) bool {
    p := filepath.Join(workspaceDir, filepath.FromSlash(strings.TrimSpace(raw)))
    _, err := os.Stat(p)
    return err == nil
}

req, err := buildReferenceViewRequest(rawRef, ws)
if err != nil {
    reply(fmt.Sprintf("cannot open %q — use a workspace-relative path like core/engine.go[:line]", rawRef))
    return
}

When it happens

Trigger: Calling parseUserLocalReference with a string that is neither a valid file/dir path in workspaceDir nor a markdown link — absolute paths outside the workspace it rejects, URLs like https://..., glob patterns, or nonexistent files, depending on parseLocalReference's rules.

Common situations: User pastes a full external URL into `/show`; the referenced file does not exist or lies outside workspaceDir; the path uses backslashes on a workspace resolved with forward slashes; typos in the filename.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• project %q: multi-workspace mode requires base_dir
• directory reference cannot carry a location
• create Agy permission overlay: %w
• read existing Agy hooks %s: %w
• write Agy hooks overlay: %w

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/b1d534e97816b69c. Report an issue: GitHub.