1. Symptoms
When the clw-router-not-found error occurs during OpenClaw application execution, developers will observe specific indicators across different operation contexts. The error manifests primarily at application startup when the router initialization phase attempts to resolve registered router components.
Shell output during application boot:
[OpenClaw] ERROR: Router 'primary-router' not found in registry
[OpenClaw] CODE: clw-router-not-found
[OpenClaw] Hint: Verify router registration in openclaw.config.js
Runtime symptoms include:
- Application fails to start with a non-zero exit code
- Router-dependent services fail to initialize
- HTTP routes become inaccessible even if defined elsewhere
- Error logs show the specific router identifier that failed resolution
- The application may hang at the routing initialization phase
Configuration validation failures:
$ openclaw validate
[WARN] Router 'api-gateway' referenced but not registered
[WARN] Router 'admin-panel' referenced but not registered
[ERROR] clw-router-not-found: 2 unresolved router references
2. Root Cause
The clw-router-not-found error stems from a fundamental mismatch between router references in your application code and the actual router components registered with the OpenClaw router registry. OpenClaw uses a centralized router management system where all available routers must be explicitly declared in the application configuration before they can be utilized.
Primary causes include:
Missing router registration: The most common cause occurs when developers define routes or references to a router that has not been added to the routers section of the OpenClaw configuration file. The router registry acts as the authoritative source for all router components, and any reference to an unregistered router will fail resolution.
Incorrect router identifier: Router lookups are case-sensitive and rely on exact string matching. If your configuration references PrimaryRouter but the registered name is primary-router, the lookup fails. This commonly occurs when developers mix naming conventions or copy identifiers from documentation examples without verifying they match their actual configuration.
Import path resolution failure: When router components are defined in separate modules, incorrect import paths can prevent the OpenClaw loader from discovering and registering the router. This happens frequently when refactoring directory structures or when routers are defined in nested module hierarchies.
Configuration file parsing errors: If the OpenClaw configuration file contains syntax errors, the router registry may not populate correctly, leading to all routers appearing unregistered even when properly declared. JSON parsing failures, trailing commas, or malformed YAML can cause this.
3. Step-by-Step Fix
Step 1: Locate the OpenClaw Configuration File
Identify the primary OpenClaw configuration file in your project root. The file is typically named openclaw.config.js, openclaw.config.ts, or openclaw.config.json depending on your project setup.
Before:
// Project structure without clear config location
/my-project
/src
/routes
index.js
app.js
package.json
After:
// Project structure with explicit config location
/my-project
/src
/routes
index.js
app.js
openclaw.config.js // <-- Configuration file present
package.json
Step 2: Verify Router Registration
Open your OpenClaw configuration file and examine the routers section. Ensure your missing router is properly declared with the correct identifier.
Before:
// openclaw.config.js
module.exports = {
server: {
port: 3000
},
routers: {
// primary-router is referenced but not registered
}
};
After:
// openclaw.config.js
module.exports = {
server: {
port: 3000
},
routers: {
'primary-router': {
type: 'express',
basePath: '/api',
middleware: ['auth', 'logging']
},
'admin-panel': {
type: 'custom',
handler: './src/routers/admin.js'
}
}
};
Step 3: Validate Router Module Imports
If your routers are defined as external modules, verify that the import paths resolve correctly relative to your configuration file location.
Before:
// openclaw.config.js with incorrect path
module.exports = {
routers: {
'api-gateway': {
type: 'custom',
handler: './routers/gateway.ts' // Wrong relative path
}
}
};
After:
// openclaw.config.js with correct path
module.exports = {
routers: {
'api-gateway': {
type: 'custom',
handler: './src/routers/gateway.ts' // Correct relative path
}
}
};
Step 4: Ensure Configuration File is Valid
Validate the syntax of your configuration file to ensure the router registry populates correctly.
Before:
# openclaw.config.yaml (malformed)
server:
port: 3000
routers:
primary-router:
type: express
basePath: /api
middleware:
- auth
- logging # Trailing comma here causes YAML parse failure
After:
# openclaw.config.yaml (valid)
server:
port: 3000
routers:
primary-router:
type: express
basePath: /api
middleware:
- auth
- logging
4. Verification
After implementing the fix, verify that the clw-router-not-found error has been resolved by following these verification steps:
Run the OpenClaw validation command:
openclaw validate
A successful validation output will display:
[OpenClaw] Configuration validated successfully
[OpenClaw] Routers registered: 3
[OpenClaw] No unresolved references found
Test application startup:
openclaw start
The application should start without emitting the clw-router-not-found error. Monitor the startup logs for any remaining warnings or errors.
Verify router availability programmatically:
const { routerRegistry } = require('@openclaw/core');
const registeredRouters = routerRegistry.list();
console.log('Available routers:', registeredRouters);
// Verify specific router exists
if (routerRegistry.has('primary-router')) {
console.log('Router registered successfully');
} else {
console.error('Router still not found');
}
Check route accessibility:
curl -I http://localhost:3000/api/health
A successful response (HTTP 200 or similar) confirms the router is functioning and routes are accessible.
5. Common Pitfalls
Avoid these frequent mistakes that trigger or persist the clw-router-not-found error:
Pitfall 1: Case-sensitive router identifiers. Router names in OpenClaw are treated as exact strings. Using PrimaryRouter when the configuration defines primary-router will fail lookup. Always maintain consistent casing throughout your configuration and code references.
Pitfall 2: Dynamic router references without registration. If your application generates router names dynamically based on environment variables or configuration, ensure the generated names are pre-registered in the configuration before runtime. OpenClaw cannot auto-register routers discovered during execution.
Pitfall 3: Forgetting to restart after configuration changes. OpenClaw caches configuration at startup. If you modify the router registration while the application is running, changes will not take effect until you restart the process.
Pitfall 4: Circular dependency in router modules. If your router handler module has circular dependencies, the module loading may fail silently, resulting in the router appearing unregistered. Use dependency analysis tools to identify and resolve circular imports.
Pitfall 5: Mixing configuration formats. OpenClaw supports multiple configuration file formats (JavaScript, TypeScript, YAML, JSON). Ensure you are editing the correct file and that only one configuration file exists in your project root to avoid conflicts.
6. Related Errors
clw-component-not-registered: This error occurs when non-router components fail registration with the OpenClaw component registry. The underlying mechanism mirrors router registration issues, but affects different component types. The fix approach is similarβverify the component exists in the configuration and imports resolve correctly.
clw-service-unavailable: When a router depends on an external service that fails to initialize, this error surfaces. While different from clw-router-not-found, the symptoms overlap since routes become inaccessible. Distinguish by checking whether the router itself is found before investigating service dependencies.
clw-route-conflict: This error indicates multiple routers have defined overlapping route patterns. While technically the routers are found, the conflict prevents proper routing. Examine your router configurations for duplicate route definitions, particularly when using wildcard patterns or default catch-all routes.