Troubleshooting

Solutions to common problems.

Server Won't Start

[shiva-core] ✗ Failed to connect to database

Cause: Database connection failed.

Fix: Check your shiva.config.lua and server.cfg:

• Is the database running? mysql -h 127.0.0.1 -u shiva -p
• Is the hostname reachable from the FiveM process?
• Does the user have correct permissions? GRANT ALL ON shiva.* TO 'shiva'@'%';

Could not load resource shiva-core

Cause: Missing dependency or load order issue.

Fix: Make sure shiva-fw is ensured before shiva-core in server.cfg.

---

Module Errors

[shiva] Contract 'IInventory' not bound

Cause: A module that depends on IInventory is loaded but no inventory module is providing it.

Fix: Make sure shiva-inventory (or a custom inventory module) is enabled and loaded before the dependent module.

[shiva-player] Migration failed: duplicate column

Cause: A migration was partially applied.

Fix:

shiva migrate --status      # see which migrations ran
shiva migrate --rollback    # roll back the last batch
shiva migrate               # re-run

---

Client Errors

NUI won't open / is a blank screen

1. Check the browser console: press F8 in-game, then open the FiveM overlay
2. Look for JS errors in nui://shiva-*/index.html
3. Make sure the NUI resource is ensured in server.cfg

---

Performance

Server tick taking > 50ms

Enable the built-in profiler:

-- In shiva.config.lua
Shiva.profiler = {
    enabled = true,
    threshold = 10,  -- log ticks over 10ms
}

Check server.log for slow ticks and which module caused them.

---

Getting More Help

• Join the Discord #support channel
• Open an issue on GitHub
• Include your shiva --version, FiveM artifact version, and the full error from the server console