Start with ryft --version, rustc --version and cargo --version. Preserve the first error and the command that produced it. Do not include database URIs, bearer tokens or environment-file contents in issue reports.
Ryft is not recognized
Invoke ryft.exe by its full path to verify the download. Add its extracted directory to your user PATH and reopen PowerShell. The VSIX’s bundled compiler supports the editor but does not automatically add a standalone CLI to PATH.
Linker or C compiler is missing
Install MSVC and the Windows SDK using Desktop development with C++ in the Visual Studio Installer. Confirm the active Rust toolchain is Windows x64 MSVC, then retry from Developer PowerShell. VS Code alone does not install these build tools.
Native builds are slow or cannot fetch dependencies
The first build compiles Rust dependencies and bundled SQLite as needed. Check connectivity to the configured Cargo registry and available disk space. Later builds reuse the native cache. Do not remove a shared cache while another build is using it. A locked build pins dependency versions; it does not mean all dependencies are available offline.
An output executable cannot be replaced
Stop the running server before rebuilding the same .exe. Check the process path before terminating anything. Use a distinct output filename if another application instance must remain running.
The dependency lock is missing or stale
Review the local dependency changes, then run ryft lock from the manifest directory. Ensure dependency paths exist on this machine and commit the updated lock with the project. A lockfile does not download missing packages.
VS Code has no diagnostics
Install the 0.3 VSIX, trust the workspace, open a saved .rz file and run Ryft: Restart Language Server. Check the Ryft output channel. If needed, set ryft.compilerPath to a working standalone compiler. Navigation and rename are most complete in type-correct projects; incomplete syntax and type annotation references remain limited.
The local extension-host verification was blocked by an active VS Code updater mutex. Wait for the editor update to finish before running that host test; successful LSP protocol tests do not substitute for it.
A declared environment variable is missing
Set every permit env "NAME" variable in the server’s environment before startup. Use nonempty values. Native --env-file parses literal values only for declared capabilities and the permitted parent control token. It does not execute shell expressions. Workers receive their own declared capabilities, rather than the parent’s entire environment.
MongoDB cannot become ready
Check DNS resolution, outbound TCP/TLS connectivity, Atlas Network Access and database-user privileges. An allowed address must match the server’s current outbound IP. Verify credential escaping in the URI without printing it. Inspect redacted runtime diagnostics; do not disable TLS verification as a connection workaround. A URI can authenticate successfully but lack permission to create an index or run test transactions.
SQLite reports an error
Check data-directory write permissions, available disk space, literal SQL and parameter counts. Read the operation’s ok flag before using rows or affected counts. App PRAGMAs, ATTACH and explicit BEGIN/COMMIT are intentionally rejected; use the transaction API. Back up with SQLite-aware tooling rather than copying a live WAL database’s main file alone.
A route returns 503 or a worker restarts
Inspect request admission limits and /_ryft/health on a trusted connection. A worker can restart after a crash or memory-limit violation. Increase budgets only after investigating the workload. Health in another worker can remain available while the affected app recovers.
Report a reproducible issue
Include the Ryft version, OS/architecture, exact command, sanitized error and smallest source that reproduces it. Mention whether --isolate was enabled. Remove credentials and private data. Current release limitations and qualification gaps are listed in production readiness.