Known Issues

Environmental and host-tooling gotchas that aren't ArcFlow bugs but can trip you on first install.

Metal GPU initialization hang#

Symptom: require('@ozinc/arcflow') hangs indefinitely on macOS.

Cause: Metal GPU kernel compilation can deadlock during module initialization on some systems.

Fix:

export ARCFLOW_METAL_FORCE_UNAVAILABLE=true

This disables Metal acceleration and falls back to CPU. All queries still work — just without GPU acceleration.

pnpm file: protocol binary sync#

Symptom: After rebuilding the native module, pnpm doesn't pick up the new .node binary.

Fix: Manually copy the binary:

# Manually copy the built .node binary into your node_modules
cp <built-binary>.node node_modules/arcflow/arcflow.<platform>.node

See Also#

• Error Codes — typed error model and recovery suggestions
• Compatibility Matrix — feature support across platforms and versions