sipeed/picoclaw · warning

invalid pid file

Error message

invalid pid file

What it means

pkg/pid sets errInvalidPidFile when the .picoclaw.pid file cannot be JSON-parsed into PidFileData or when the recorded PID is <= 0 (readPidFileUnlocked). The package self-heals: ReadPidFileWithCheck logs 'invalid pid file, remove it' and deletes it, and WritePidFile treats it as stale and removes it before writing a fresh one — so users normally see a warning log, not a crash.

Source

Thrown at pkg/pid/pidfile.go:20

import (
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"sync"
	"time"

	"github.com/sipeed/picoclaw/pkg/config"
	"github.com/sipeed/picoclaw/pkg/logger"
)

const pidFileName = ".picoclaw.pid"

var errInvalidPidFile = errors.New("invalid pid file")

// PidFileData is the JSON structure stored in the PID file.
type PidFileData struct {
	PID     int    `json:"pid"`
	Token   string `json:"token"`
	Version string `json:"version"`
	Port    int    `json:"port"`
	Host    string `json:"host"`
}

var pidMu sync.Mutex

// pidFilePath returns the absolute path for the PID file given the home directory.
func pidFilePath(homePath string) string {
	return filepath.Join(homePath, pidFileName)
}

// generateToken creates a cryptographically random 32-character hex token.

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Usually nothing — picoclaw detects and deletes the invalid file automatically on next start
2. If the warning recurs, delete the file manually: rm "$PICOCLAW_HOME/.picoclaw.pid" (or ~/.picoclaw/.picoclaw.pid)
3. Make sure only one gateway instance uses that PICOCLAW_HOME and that the directory is writable by the gateway user

Example fix

# before: corrupt pid file blocks/confuses status
$ cat ~/.picoclaw/.picoclaw.pid
not-json

# after
$ rm ~/.picoclaw/.picoclaw.pid
$ picoclaw gateway

When it happens

Trigger: A .picoclaw.pid in PICOCLAW_HOME (default home) that is empty, truncated, hand-edited, or written by another tool; a JSON body that unmarshals to PID 0/negative; a leftover file on a shared volume from a crashed container.

Common situations: Gateway killed -9 mid-write (atomic rename normally prevents this, but external truncation can still happen); someone echoed into the file; a different program using the same filename in the same directory; version migrations that left an incompatible schema.

Related errors

• read media file: %w
• events: bus is closed
• session already completed
• create output dir: %w
• write result: %w

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