Skip to main content

Troubleshooting

Start with the repository's locked toolchain and the hst diagnostic commands. Avoid installing a second global copy of Hosanna Tools.

Verify the Environment​

node --version
npx hst version
npx hst env check
npx hst compiler:status

Current hosanna-ui-samples-public expects Node.js 24.17.0. In another application, use its .nvmrc and package.json engines instead of copying that version blindly.

Generated Imports Cannot Be Resolved​

Generated factories and state contracts live below src-generated and are normally ignored by Git. Generate them before direct TypeScript or Vitest commands:

npm run generate

The sample repository's normal npm test, npm run build, and hst run workflows generate them automatically.

Dev Port Is Occupied​

The active Vite port comes from .hosanna-tools/run.json or --vitePort. The sample repository uses 5170; HST's built-in default is 5173.

First, inspect the owning process:

lsof -nP -iTCP:5170 -sTCP:LISTEN

Stop the relevant dev session normally. For a separate run, choose a complete non-conflicting port configuration rather than force-killing an unknown process:

npx hst run web dev browser --vitePort 5180

Browser Opens the Wrong or Stale Screen​

  • Run from the application repository root.
  • Inspect .hosanna-tools/run.json for the selected app, port, and default profile.
  • Use --dry-run --explain to see how HST resolved the launch.
  • Check launch query parameters such as defaultSpringboardRig and noAutoOpenLastScreen.
npx hst run web dev browser --dry-run --explain

Hosanna is not a React package. Do not add react, an imaginary public hosanna-ui package, or arbitrary @types packages to solve generated-source or SDK-install errors.

A Native App Shows an Old Runtime​

Confirm the exact target, then rebuild/install through HST:

npx hst target:list --platform android --target sim --json
npx hst run android dev sim --device emulator-5554 --replace

If logs refer to an unexpected runtime or the wrong package, suspect a stale install or wrong selected simulator/device before changing framework bootstrap code. Force-stop or uninstall only the exact package on the exact selected target, then rerun the supported launcher.

Focus or Input Does Nothing​

  • Give the intended starting control .isInitialFocus().
  • Verify every explicit nextFocusMap ID exists in the current view tree.
  • Click the dark browser background before using remote-style keyboard input; browser-native inputs intentionally keep their own key events.
  • On Apple TV Simulator, confirm the Hosanna app is frontmost and keyboard capture is enabled.
  • On device, inspect the focus hierarchy and input path with Hosanna diagnostics instead of inferring focus from pixels alone.

Licensed SDK or Compiler Cannot Install​

  • Confirm HSC_LICENSE_KEY is available without printing it.
  • Run npx hst license:status.
  • Check the exact SDK/compiler versions in hosanna.json.
  • Do not replace or discard an existing modified hosanna-ui/ install without preserving the work and explicitly choosing a source mode.

See Compiler License and Tool Setup and Upgrading.

Talk to us