What causes "failed to initialize json file %s: %w" in yorukot/superfile?

Read the wrapped error for path and errno; check whether the parent directory exists (`ls -la $(dirname )`).

failed to initialize json file %s: %w

Error message

failed to initialize json file %s: %w

What it means

InitJSONFile creates a JSON file initialized to the literal `null` if it doesn't exist yet, writing with os.WriteFile and ConfigFilePerm; this error wraps a failure of that write. A `null` root is valid JSON that unmarshals into nil pointers/slices, which the pinned-file manager expects. The failure is filesystem-related, not JSON-related.

Source

Thrown at src/pkg/utils/file_utils.go:317

	}
	var sb strings.Builder
	lastSegmentStart := 0
	for _, r := range line {
		if r == '\t' {
			newSegmentSize := ansi.StringWidth(sb.String()[lastSegmentStart:])
			sb.WriteString(strings.Repeat(" ", TabWidth-newSegmentSize%TabWidth))
			lastSegmentStart = sb.Len()
			continue
		}
		sb.WriteRune(r)
	}
	return sb.String()
}

func InitJSONFile(path string) error {
	if _, err := os.Stat(path); os.IsNotExist(err) {
		if err = os.WriteFile(path, []byte("null"), ConfigFilePerm); err != nil {
			return fmt.Errorf("failed to initialize json file %s: %w", path, err)
		}
	}
	return nil
}

View on GitHub (pinned to b72f550bc6)

Solutions

Read the wrapped error for path and errno; check whether the parent directory exists (`ls -la $(dirname <path>)`).
Create the parent directory (CreateDirectories) before InitJSONFile.
Verify write permission on the directory for the runtime user; fix ownership/chmod.
Ensure the path isn't an existing directory; correct the configured path if so.
At the call site, fail gracefully (e.g. start with an empty pinned list) and log the reason.

Example fix

// before
err := utils.InitJSONFile(pinnedPath)
// after
if err := utils.CreateDirectories(filepath.Dir(pinnedPath)); err != nil { return err }
if err := utils.InitJSONFile(pinnedPath); err != nil {
    return fmt.Errorf("init pinned list %s: %w", pinnedPath, err)
}

Defensive patterns

Strategy: validation

Validate before calling

func ensureJSONCreatable(path string) error {
    dir := filepath.Dir(path)
    if info, err := os.Stat(dir); err != nil || !info.IsDir() {
        return fmt.Errorf("parent dir %s missing", dir)
    }
    f, err := os.CreateTemp(dir, ".t*")
    if err != nil { return err }
    f.Close(); os.Remove(f.Name())
    return nil
}

Try / catch

if err := utils.InitJSONFile(pinnedPath); err != nil {
    log.Warnf("pinned list unavailable: %v", err)
    pinned = nil // degrade to empty pinned list
}

Prevention

Create the parent directory before initializing JSON state files.
Confirm state dirs survive restarts and are writable (avoid read-only volumes).
Treat `null` as a valid empty state when loading so first-run works.
Log the failing path from the wrapped error for quick triage.

When it happens

Trigger: NewPinnedFileManager calling InitJSONFile when the pinned-list file's parent directory doesn't exist or isn't writable, the path exists as a directory, the disk is full, or the process lacks permission.

Common situations: First-run initialization in a read-only or non-existent state directory; pinned-file path configured under a directory never created; running the app under a user that can't write the config dir; containerized setups with ephemeral/read-only volumes.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of yorukot/superfile@b72f550bc6 (2026-09-01). Data as JSON: /api/errors/1f7e8bec69de3cbf. Report an issue: GitHub.