sipeed/picoclaw · error

failed to register audio: %w

Error message

failed to register audio: %w

What it means

store.Store(file.Name(), media.MediaMeta{...}, scope) failed at pkg/audio/tts/tts.go:177 while registering the finished temp audio file into the media store under scope "tool:send_tts:<channel>:<chatID>:<unixnano>". The wrapped error comes from the media store implementation — typically a copy/import into the store's backing directory failing or the store being unavailable/misconfigured. Because removeTemp stays true on this path, the temp file is cleaned up and the caller gets no reference.

Source

Thrown at pkg/audio/tts/tts.go:177

	if filename == "" {
		filename = fmt.Sprintf("tts-%d%s", time.Now().Unix(), fileExt)
	}

	ext := strings.ToLower(filepath.Ext(filename))
	if ext == "" {
		filename += fileExt
	} else if ext != fileExt {
		filename = strings.TrimSuffix(filename, filepath.Ext(filename)) + fileExt
	}

	scope := fmt.Sprintf("tool:send_tts:%s:%s:%d", channel, chatID, time.Now().UnixNano())
	ref, err := store.Store(file.Name(), media.MediaMeta{
		Filename:    filename,
		ContentType: contentType,
		Source:      "tool:send_tts",
	}, scope)
	if err != nil {
		return "", fmt.Errorf("failed to register audio: %w", err)
	}
	removeTemp = false

	return ref, nil
}

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Read the wrapped error — it names the store operation and underlying errno
2. Verify the media store directory exists, is owned by the service user, and is writable: mkdir -p <store> && sudo -u <svc> test -w <store>
3. Check disk space on the store's filesystem (it may be a different volume than the temp dir)
4. Restart the service after fixing media store config so the store re-initializes

Example fix

# before: store dir owned by root, service runs as 'picoclaw'
ls -ld /var/lib/picoclaw/media  # drwx------ root root

# after:
chown -R picoclaw:picoclaw /var/lib/picoclaw/media
chmod 700 /var/lib/picoclaw/media

func mediaStoreWritable(storeDir string) error {
    if err := os.MkdirAll(storeDir, 0o700); err != nil { return err }
    probe := filepath.Join(storeDir, ".probe")
    if err := os.WriteFile(probe, nil, 0o600); err != nil { return err }
    return os.Remove(probe)
}

if _, err := tts.SynthesizeToStore(ctx, text, ch, chatID, name); err != nil {
    if strings.Contains(err.Error(), "failed to register audio") {
        // temp audio worked, store import failed: check store volume/config
        log.Print("media store import failed; verify store dir perms and space")
    }
    return err
}

When it happens

Trigger: Store's target directory unwritable or full when importing the temp file; store not initialized / nil from missing media config; store backend rejecting the metadata (e.g. filename/content-type handling); filesystem errors moving the file into the store.

Common situations: Media store dir on a different volume than the temp dir, with the store volume full or read-only; running with a media store path the service user cannot write; store dir deleted while service runs.

Related errors

• failed to create media temp dir: %w
• create output dir: %w
• failed to save config: %w
• ✗ failed to create skills directory: %w
• media store not configured

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/1f76616bb4810eb1. Report an issue: GitHub.