tailscale/tailscale · error

reading child %d of %x: %w

Error message

reading child %d of %x: %w

What it means

While listing an AUM's children from the in-memory index (used by FS.Children), reading one child AUM from disk failed; the message carries the child's position i in the parent's child list and the parent hash. The wrapped error comes from the underlying read: file missing/open error, CBOR decode failure, or an AUM-vs-filename hash mismatch — i.e. the on-disk state diverged from the index.

Source

Thrown at tka/tailchonk.go:451

	c.mu.RUnlock()

	c.mu.Lock()
	defer c.mu.Unlock()
	if err := c.buildIndexLocked(); err != nil {
		return nil, err
	}
	return c.childAUMsFromIndexLocked(prevAUMHash)
}

// childAUMsFromIndexLocked returns children from the in-memory index. The
// caller must hold c.mu for reading or writing.
func (c *FS) childAUMsFromIndexLocked(prevAUMHash AUMHash) ([]AUM, error) {
	children := c.parentIndex[prevAUMHash]
	out := make([]AUM, 0, len(children))
	for i, h := range children {
		aum, err := c.aumLocked(h)
		if err != nil {
			return nil, fmt.Errorf("reading child %d of %x: %w", i, prevAUMHash, err)
		}
		out = append(out, aum)
	}
	return out, nil
}

func (c *FS) get(h AUMHash) (*fsHashInfo, error) {
	dir, base := c.aumDir(h)
	f, err := os.Open(filepath.Join(dir, base))
	if err != nil {
		return nil, err
	}
	defer f.Close()

	m, err := cborDecOpts.DecMode()
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 6e0912f979)

Solutions

1. Unwrap the error to identify the file and cause (missing vs decode vs hash mismatch).
2. Restore or re-sync the affected AUM from a healthy peer (the remote's MissingAUMs can supply it).
3. Stop external writers on the TKA directory; reopen the FS after any out-of-band repair so indexes rebuild.

children, err := fs.Children(parentHash)
if err != nil {
	// unwrap: fs.ErrNotExist => AUM file vanished; cbor decode => corruption
	return fmt.Errorf("loading children of %x: %w", parentHash, err)
}

When it happens

Trigger: Calling Children(parentHash) after an indexed AUM file was deleted, truncated, or corrupted behind the running process, or on any I/O error reading it.

Common situations: External modification of the TKA directory (ChonkDir requires exclusive write access for the FS's lifetime); disk/filesystem problems; backup or sync tools touching AUM files while tailscaled runs.

Related errors

• reading head %x: %w
• reading prefix dir: %v
• reading %x: %v
• computeStateAt: %v
• local syncOffer: %v

AI-assisted analysis of tailscale/tailscale@6e0912f979 (2026-08-18). Data as JSON: /api/errors/892928acc429f44c. Report an issue: GitHub.