Troubleshooting

Troubleshooting

This page collects common issues and first checks.

Local App Does Not Start

Check Node version:

node --version

Cindr3D expects Node.js 22.12.0 or newer.

Refresh dependencies:

npm install

If Vite cache state appears stale:

npm run dev:fresh

Build Fails

Run the checks separately to narrow down the failure:

npm run typecheck
npm run lint
npm run test:run
npm run build

If the failure mentions WASM artifacts, also run:

npm run verify:wasm-build
npm run check:wasm-budget

Hosted App Shows a Blank Page on Refresh

Cindr3D is a single-page app. Static hosts must fall back unknown routes to index.html.

For Nginx, the important rule is:

try_files $uri $uri/ /index.html;

Assets 404 After Deploy

Confirm the deployed directory includes:

index.html
assets/

If deploying a zip asset for the updater, the archive can also contain:

dist/index.html
dist/assets/

AI MCP Client Cannot Connect

Check these first:

• The Cindr3D browser tab is open.
• The dev server is running.
• The MCP URL includes the current token from the AI MCP status badge.
• The client is connecting from localhost.
• The MCP port has not been changed by CINDR3D_MCP_PORT.

Default URLs:

http://localhost:5173
http://localhost:5174/mcp?token=...

If the token might be stale, rotate it from the AI status badge and re-add the MCP server in the client.

Printer Does Not Show Expected Tabs

Cindr3D adapts tabs and commands to the connected printer and detected firmware.

Check:

• Printer profile firmware type
• Connection status
• Firmware version
• Whether the feature is firmware-supported
• Whether the required plugin or service is enabled on the printer side

Examples:

• Klipper object cancellation depends on EXCLUDE_OBJECT.
• RRF object cancellation depends on M486 support.
• Marlin object cancellation depends on a recent enough firmware and labeled G-code.

Object Cancellation Is Disabled

Object cancellation requires labeled G-code.

For Cindr3D-sliced jobs, labels are emitted automatically.

For other slicers:

• Enable object labels in PrusaSlicer, SuperSlicer, or OrcaSlicer.
• Use Cura's Label Objects post-processing script.

MQTT or Home Assistant Is Quiet

Check:

• Broker URL and credentials
• Topic names
• Network access from the browser or bridge
• Event rules enabled in Cindr3D
• Home Assistant discovery settings
• Whether the printer is actively publishing state

Start with a single event such as PRINT_START or DONE, confirm delivery, then expand automation coverage.

Orange Pi Updates Do Not Apply

Check:

• The updater service is installed and running.
• Nginx routes /api/update/status and /api/update/apply correctly.
• The updater token matches the local browser configuration.
• The latest GitHub release includes a compatible cindr3d-dist.zip asset.
• The archive layout includes either root-level index.html and assets/, or a dist/ directory containing them.