M MortelOS Docs

Version 0

Troubleshooting

Common MortelOS Starter installation and boot fixes.

Start every boot issue with:

php artisan starter:doctor
vendor/bin/pest

mortelos --version is stale

Your shell is loading an older installed CLI before the current one.

type -a mortelos
mortelos --version

Install the current bin/mortelos into the first directory shown by type -a, or remove the stale copy. On macOS, /opt/homebrew/bin often appears before /usr/local/bin.

GitHub SSH fails during mortelos new

mortelos v0.1.1 clones mortelos/starter over HTTPS by default. If you still see:

git@github.com: Permission denied (publickey).

you are running an older CLI. Reinstall the current script and run:

mortelos --version

It should return mortelos v0.1.1 or newer.

mortelos/ui cannot be installed

Composer may need access to private MortelOS package repositories.

ssh -T git@github.com
composer install

If you install via HTTPS with a token, configure Composer authentication with a GitHub token.

Vite manifest not found

Frontend assets were not built.

npm install --ignore-scripts
npm run build

View [layouts.guest] not found

The login page expects resources/views/layouts/guest.blade.php.

Restore it from Git:

git restore resources/views/layouts/guest.blade.php

Missing starter route class config

If you see:

LogicException: Missing starter route class config [...]

one of the route-backed auth config keys is null in config/starter.php. Fill the required class config keys or restore the starter defaults.

Required keys:

  1. auth.post_login_redirect_resolver.
  2. auth.controllers.password_login.
  3. auth.controllers.passkey_authenticated.
  4. auth.controllers.accept_invitation.
  5. users.resolver.
  6. users.access_resolver.

Login loops back to login

Check:

  1. After login, Auth::check() must be true.
  2. auth.post_login_redirect_resolver must return a valid URL string.
  3. The target route returned by the resolver exists.

These are optional surfaces and degrade silently when their resolvers are null.

Surface Config to bind
Sidebar navigation.sidebar_resolver
Universal search navigation.universal_search_resolver
Governance governance.resolver and governance.access_resolver
Users users.resolver
Onboarding onboarding.resolver
Inbox detail types inbox.item_type_resolver
Chat panel chat.settings_service and chat.conversation_panel_component

Bind these only when the capability map calls for them.