{"record":{"id":"5df7483d42877616","repo":"sipeed/picoclaw","slug":"invalid-pid-file","errorCode":null,"errorMessage":"invalid pid file","messagePattern":"invalid pid file","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"pkg/pid/pidfile.go","lineNumber":20,"sourceCode":"\nimport (\n\t\"crypto/rand\"\n\t\"encoding/hex\"\n\t\"encoding/json\"\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"sync\"\n\t\"time\"\n\n\t\"github.com/sipeed/picoclaw/pkg/config\"\n\t\"github.com/sipeed/picoclaw/pkg/logger\"\n)\n\nconst pidFileName = \".picoclaw.pid\"\n\nvar errInvalidPidFile = errors.New(\"invalid pid file\")\n\n// PidFileData is the JSON structure stored in the PID file.\ntype PidFileData struct {\n\tPID     int    `json:\"pid\"`\n\tToken   string `json:\"token\"`\n\tVersion string `json:\"version\"`\n\tPort    int    `json:\"port\"`\n\tHost    string `json:\"host\"`\n}\n\nvar pidMu sync.Mutex\n\n// pidFilePath returns the absolute path for the PID file given the home directory.\nfunc pidFilePath(homePath string) string {\n\treturn filepath.Join(homePath, pidFileName)\n}\n\n// generateToken creates a cryptographically random 32-character hex token.","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/pkg/pid/pidfile.go#L2-L38","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Usually nothing — picoclaw detects and deletes the invalid file automatically on next start","If the warning recurs, delete the file manually: rm \"$PICOCLAW_HOME/.picoclaw.pid\" (or ~/.picoclaw/.picoclaw.pid)","Make sure only one gateway instance uses that PICOCLAW_HOME and that the directory is writable by the gateway user"],"exampleFix":"# before: corrupt pid file blocks/confuses status\n$ cat ~/.picoclaw/.picoclaw.pid\nnot-json\n\n# after\n$ rm ~/.picoclaw/.picoclaw.pid\n$ picoclaw gateway","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Rely on the built-in self-healing: picoclaw logs and removes the invalid pid file automatically","Keep PICOCLAW_HOME on a reliable filesystem and writable by the gateway user","Do not hand-edit .picoclaw.pid; delete it instead if something is wrong"],"tags":["pid","lifecycle","filesystem","self-healing"],"backgroundTag":null,"analyzedSha":"49183d7e8daed0dba89ddbb6fcb60089401d9680","analyzedAt":"2026-08-15T21:55:41.315Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}