Troubleshooting and Common Pitfalls

1) No workers/ directory found

Cause: command executed outside a bootstrapped repo.

Fix:

npx worker-cli init
# or set explicit root
FLOWMAKER_WORKERS_ROOT=/abs/path/to/repo npx worker-cli consistency

2) Build fails with REGISTRY is not defined

Cause: missing REGISTRY in env.

Fix:

echo 'REGISTRY=registry.example.com' >> .env
npx worker-cli build my-worker

3) Non-interactive create says required flags are missing

Cause: providing one non-interactive flag triggers full non-interactive requirements.

Fix:

npx worker-cli create --type node --name my-worker --box-type pipe --icon code

4) Registration test timeout

Cause: container cannot reach mock hub or startup is slow.

Fix:

MOCK_HUB_HOST_IP=172.17.0.1 TIMEOUT=90 npx worker-cli test ./workers/my-worker registry.example.com/myteam/my-worker:1.0.0

5) Slow builds

Try parallel mode and keep proxy enabled:

npx worker-cli build --parallel=4

If proxy causes issues in your environment:

npx worker-cli build --parallel=4 --no-proxy

6) Worker skipped during build

Cause: missing Dockerfile, unknown runtime type, or missing version.

Fix:

• Ensure worker has Dockerfile.
• Ensure one of: package.json, pyproject.toml, src/*.csproj.
• Ensure version exists in runtime project metadata.

7) Version mismatch in test results

Cause: registration metadata version differs from project file version.

Fix checklist:

1. Confirm project version in worker metadata file.
2. Rebuild image.
3. Re-run test.

[WARNING!report/RELEASE BLOCKER] Do not push release tags when registration reports version mismatch.

References

• sdk/worker/repo-management/src/commands/build.ts
• sdk/worker/repo-management/src/commands/test-container.ts
• sdk/worker/repo-management/src/lib/context.ts