Skip to main content

​
Troubleshooting

This guide covers common issues you might encounter when using better-openclaw and how to resolve them.

​
Installation Issues

​
pnpm not found

Problem: pnpm: command not found when running pnpm install Solution: Enable corepack and install pnpm: 
corepack enable
corepack prepare pnpm@latest --activate
better-openclaw enforces pnpm as the package manager. Using npm or yarn will fail.

​
Node version mismatch

Problem: Build fails with Node.js version errors Solution: Ensure you’re using Node.js 20 or higher: 
node --version  # Should output v20.x.x or higher
If you need to upgrade, use nvm: 
nvm install 20
nvm use 20

​
Dependencies fail to install

Problem: pnpm install fails with errors Solution: Clear caches and reinstall: 
rm -rf node_modules
rm -rf packages/*/node_modules
pnpm store prune
pnpm install

​
Service Definition Issues

​
”Invalid service definition” error

Problem: Tests fail with schema validation errors Solution: Ensure your service definition matches the schema. Common mistakes:
  1. Missing required fields: 
    // ❌ Bad: missing required fields
export const myService = {
  id: "my-service",
  name: "My Service"
};

// ✅ Good: all required fields present
export const myService: ServiceDefinition = {
  id: "my-service",
  name: "My Service",
  description: "A brief description",
  category: "database",
  icon: "🔧",
  image: "my-service/image",
  imageTag: "1.0.0",
  docsUrl: "https://example.com",
  // ... other required fields
};
  2. Invalid ID format: 
    // ❌ Bad: uppercase or underscores
id: "My_Service"

// ✅ Good: lowercase with hyphens
id: "my-service"
  3. Invalid category: 
    // ❌ Bad: category doesn't exist
category: "custom-category"

// ✅ Good: use a valid category from ServiceCategorySchema
category: "database"
Run pnpm test to see detailed validation errors.

​
Service not appearing in CLI

Problem: Created a service definition but it doesn’t show up in the CLI Solution: Ensure you’ve registered it in packages/core/src/services/definitions/index.ts: 
// 1. Add export
export { myServiceDefinition } from "./my-service.js";

// 2. Add import
import { myServiceDefinition } from "./my-service.js";

// 3. Add to array
export const allServiceDefinitions: ServiceDefinition[] = [
  // ... existing services
  myServiceDefinition,
];
Rebuild the project: 
pnpm build

​
Docker Compose Issues

​
Port conflicts

Problem: Error: Port 8080 is already in use Solution: Either stop the conflicting service or use port overrides: 
# Check what's using the port
lsof -i :8080

# Kill the process
kill -9 <PID>
Or override the port when generating: 
{
  "portOverrides": {
    "my-service": {
      "8080": 8081
    }
  }
}

​
Services fail health checks

Problem: Docker Compose shows services as unhealthy Solution:
  1. Check container logs: 
    docker compose -f output/docker-compose.yml logs my-service
  2. Verify health check command is correct: 
    healthcheck: {
  test: "curl -f http://localhost:8080/health || exit 1",
  interval: "30s",
  timeout: "10s",
  retries: 3,
  startPeriod: "30s"  // Give service time to start
}
  3. Test health check manually: 
    docker compose exec my-service curl http://localhost:8080/health

​
Volume permission issues

Problem: Service fails with “Permission denied” when writing to volumes Solution: Check volume permissions and user configuration: 
services:
  my-service:
    user: "1000:1000"  # Match host user
    volumes:
      - my-service-data:/data
Or fix permissions manually: 
docker compose down
sudo chown -R 1000:1000 ./volumes/my-service-data
docker compose up -d

​
Skill Pack Issues

​
Skill not loading in OpenClaw

Problem: Created a SKILL.md but OpenClaw doesn’t recognize it Solution:
  1. Verify YAML frontmatter is valid: 
    ---
name: my-skill
description: "Skill description"
metadata:
  openclaw:
    emoji: "🔧"
---
  2. Ensure skill is referenced in service definition: 
    skills: [{ skillId: "my-skill", autoInstall: true }]
  3. Check skill file location: 
    skills/
  my-skill/
    SKILL.md  # Must be in a subdirectory

​
Environment variables not substituted

Problem: Skill references {{VAR_NAME}} but it’s not replaced Solution: Ensure the variable is defined in openclawEnvVars of the service definition: 
openclawEnvVars: [
  {
    key: "VAR_NAME",
    defaultValue: "default-value",
    secret: false,
    description: "Description of the variable",
    required: true
  }
]

​
Generation Issues

​
Resolver fails with dependency conflicts

Problem: Error: Service conflicts with existing service Solution: Review the conflictsWith field in service definitions. You can’t have both conflicting services in the same stack: 
// redis.ts
conflictsWith: ["valkey"]  // Redis and Valkey can't coexist

// Solution: Remove one of the conflicting services
Check resolver warnings: 
pnpm --filter cli start
# Look for warnings about conflicts

​
Missing dependencies not auto-added

Problem: Service requires another service but it’s not included Solution: Use the requires field to automatically pull in dependencies: 
export const n8nDefinition: ServiceDefinition = {
  // ...
  requires: ["postgresql"],  // Auto-includes PostgreSQL
};

​
Out of memory errors during generation

Problem: Generation fails with OOM errors Solution:
  1. Check total memory requirements: 
    minMemoryMB: 512  // Set realistic memory requirements
  2. Reduce the number of services in your stack
  3. Increase Docker’s memory limit: 
    # In Docker Desktop: Settings → Resources → Memory
# For Docker on Linux, edit /etc/docker/daemon.json
{
  "default-runtime": "runc",
  "default-shm-size": "2G"
}

​
Testing Issues

​
Snapshot tests fail after changes

Problem: pnpm test fails with snapshot mismatches Solution: If changes are intentional, update snapshots: 
npx vitest run -u packages/core/src/composer.snapshot.test.ts
Review the diff carefully before committing: 
git diff

​
Type errors in tests

Problem: TypeScript errors when running tests Solution: Ensure all types are imported correctly: 
import type { ServiceDefinition } from "../../types.js";  // ✅ Good: uses .js extension
import type { ServiceDefinition } from "../../types";     // ❌ Bad: missing .js
Run type checking: 
pnpm typecheck

​
Native (Bare-Metal) Issues

​
Native install script fails

Problem: Bare-metal deployment fails to install services Solution: Check nativeRecipes platform compatibility: 
nativeRecipes: [
  {
    platform: "linux",  // Must match host OS
    installSteps: [
      // Use conditional commands
      "command -v redis-server || sudo apt-get install -y redis-server"
    ]
  }
]
Test install steps manually: 
sh native/install-redis.sh

​
Service not connecting via host.docker.internal

Problem: OpenClaw gateway can’t reach native service Solution: Ensure bareMetalNativeHost is enabled in compose options: 
{
  deploymentType: "bare-metal",
  bareMetalNativeHost: true  // Adds extra_hosts to gateway
}
Test connectivity: 
docker compose exec openclaw-gateway ping host.docker.internal

​
Build Issues

​
ESM import errors

Problem: Error: Cannot find module or ERR_MODULE_NOT_FOUND Solution: Always use .js extensions in imports (even for TypeScript files): 
// ❌ Bad
import { myFunc } from "./utils";
import type { MyType } from "./types";

// ✅ Good
import { myFunc } from "./utils.js";
import type { MyType } from "./types.js";

​
Biome formatting issues

Problem: pnpm lint fails with formatting errors Solution: Auto-fix formatting: 
pnpm check --apply
Or manually fix: 
npx @biomejs/biome format --write .

​
Getting Help

If you’re still stuck:
1

Check the Logs

Look for detailed error messages in:
  • CLI output
  • Docker Compose logs
  • Test output
2

Search Issues

Check if others have reported similar problems:
3

Create a Minimal Reproduction

Create a minimal example that reproduces the issue:
git clone https://github.com/bidewio/better-openclaw.git
cd better-openclaw
pnpm install
# ... steps to reproduce
4

Report the Issue

Open a new issue with:
  • Clear description of the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Node version, Docker version)
  • Relevant logs or error messages
Before opening an issue, make sure you’re on the latest version:
git pull origin main
pnpm install
pnpm build

Build docs developers (and LLMs) love

Get started for freeTalk to us