Heuristic:Openclaw Openclaw Warning Suppression For Known Deprecations
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Maintenance |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Pattern for suppressing known Node.js deprecation and experimental warnings from dependencies (punycode DEP0040, util._extend DEP0060, SQLite experimental) to keep console output clean.
Description
OpenClaw installs a process-level warning filter that suppresses specific known warnings originating from dependencies. These warnings cannot be fixed in OpenClaw's own code (they come from transitive dependencies like `punycode` and `util._extend`) and would otherwise pollute console output with noise that confuses users. The filter is installed once via a global Symbol guard to prevent double-registration. Unrecognized warnings are still forwarded to stderr with full stack traces.
Usage
Apply this heuristic when new Node.js deprecation warnings appear in the console output that originate from dependencies. Add the warning code and message pattern to the `shouldIgnoreWarning` function. Only suppress warnings that are: (1) from dependencies OpenClaw cannot control, (2) known to be harmless, and (3) confirmed to not indicate a real issue.
The Insight (Rule of Thumb)
- Action: Add specific warning code + message filters to `src/infra/warnings.ts`.
- Value: Filter by both `code` (e.g., `DEP0040`) and `message` substring for precision.
- Trade-off: Suppressed warnings may hide future issues if the filter is too broad. Always match both code AND message.
- Guard: Use `Symbol.for()` singleton pattern to prevent double-registration of the warning handler.
Reasoning
Node.js deprecation warnings for `punycode` (DEP0040) and `util._extend` (DEP0060) are triggered by deep transitive dependencies that OpenClaw cannot update. The SQLite experimental warning is expected because OpenClaw intentionally uses the Node.js built-in SQLite module. Suppressing these specific warnings improves user experience without hiding genuine issues.
Code Evidence from `src/infra/warnings.ts:1-40`:
const warningFilterKey = Symbol.for("openclaw.warning-filter");
function shouldIgnoreWarning(warning: Warning): boolean {
if (warning.code === "DEP0040" && warning.message?.includes("punycode")) {
return true;
}
if (warning.code === "DEP0060" && warning.message?.includes("util._extend")) {
return true;
}
if (
warning.name === "ExperimentalWarning" &&
warning.message?.includes("SQLite is an experimental feature")
) {
return true;
}
return false;
}
export function installProcessWarningFilter(): void {
const globalState = globalThis as typeof globalThis & {
[warningFilterKey]?: { installed: boolean };
};
if (globalState[warningFilterKey]?.installed) {
return;
}
globalState[warningFilterKey] = { installed: true };
process.on("warning", (warning: Warning) => {
if (shouldIgnoreWarning(warning)) {
return;
}
process.stderr.write(`${warning.stack ?? warning.toString()}\n`);
});
}