Troubleshooting

Last updated on

Start with the server journal. opx_infinity names every problem it can see there, client-side module failures included (forwarded to the server as client module: ... lines). Search the journal for the quoted text.

Boot

no database: nobody will be able to connect until this is fixed.

Also [storage] no database: .... The database is unreachable: the resource boots, but no character can load.

• Fix the connection string and restart. A database that comes back later is only picked up by a restart.

[storage] creating <table> failed: ...

A CREATE TABLE failed. Boot is degraded (schema failed).

• Check the database user's rights.

opx_infinity <version> up -- degraded: <reason>

Boot finished with a problem; the reason follows.

• Read the lines above it.

[<module>] init failed: ...

Or api, start. A module raised in that phase and is failed; its dependants become unavailable.

• Read the error.

[<module>] requires "<other>", which is ...

A required module is off, missing or failed.

• Enable or fix <other>.

[<module>] contract "<name>" is withdrawn with it

A failed module had published a contract; it is removed.

• Fix the failing module.

[boot] <name> is running and also places players

Another resource also moves players.

• Remove it. See CONFLICTING_PLACERS.

[commands] the alias "<alias>" for "<command>" was skipped: ...

Another resource owns that short name. Harmless; the long command works.

• Change the alias in COMMAND_ALIASES.

[tune] no tunables panel on this host; configured defaults are used

Tunables cannot be changed live. Harmless.

Players stuck at the loading screen

[gate] no resource here emits ... so the __platform hold never clears

The line names open77:session:gameplayReady. Nobody tells the platform the player is in the world; the appearance module sends it.

• Make sure appearance is started.

[gate] <id> spent too long behind the gate; releasing without them

The entry flow did not finish in time and the gate was opened anyway.

• Read the lines about that player; check character, spawn and form.

client module: form failed ...

Or any client module. A client module failed, often on the instruction budget.

• See Two runtimes. Report it with the full line.

Something on screen stopped working

• Ask the player to run /opx.client in the game console: it prints the client module states and the job list to their client log.

Staff menu or eye rows missing

A row a role may not run is greyed in the staff menu and not shown on the target eye. The admin module logs the missing grants once per registration:

[admin] target rows, player 3: 25 staff rows on the eye; 12 hidden, this ACL does not grant: opx.inventory.open opx.weather.set

• Add command.<name> for each listed name to acl.jsonc. See Permissions.

/opx.admin.self.model answers models_unavailable

The model commands need the host's players.setModel native, which is in no published server build as of 2.31.13+op77.78. The admin module checks for it before every call, answers models_unavailable and logs [admin] this build has no players.setModel native: ....

• Nothing is broken; the commands start working on a build that has the native.

open77_validate reports errors

The devkit validator reports some errors on opx_infinity that are not real problems (checked against 2.31.13+op77.78). Ignore these; treat anything else as real.

No loading cover, or the HUD stays up during a load

[loading] this client has no Open77.screen.loadingState; ...

In the player's client log. The loading module needs an updated Open77 client. Harmless: nothing is hidden and no cover is shown.

• Ask the player to update their client.

[loading] the loading state was refused: permission_denied

screen.read is missing from open77.lua.

• Restore the shipped manifest permission.

Door locks

[doorlock] BACKEND = 'networked' but open77_doors is not running: ...

Every lock falls back to the local backend.

• Add open77_doors to resources.load. Note that open77_doors depends on open77_elevators, which takes the lifts away from the elevators module.

[doorlock] ready: N door(s), M refused, backend local

The local backend only locks each client's own copy of the door: a modified client can walk through. Use networked for doors that matter. See Backends.

[doorlock] config: DOORS.<key> refused: <code>

A door in config/doorlock.lua is invalid and was skipped. Also saved door #<id> refused for a row in the database.

• Fix the door; the code is in the refusal codes.

Admins are asked for the code

By design since PR #86. Grant opx.doorlock.bypass and set STAFF_BYPASS = true, or grant one door with the right doorlock.<id>. Staff holding command.opx.doorlock.save can read the code in the panel.

Fuel

My car won't start: empty tank

At 0 litres the server cuts the engine, and cuts it again on every tick it is found running: starting it only works for a second.

• Fill it at a pump, pour a fuel can, or as staff /opx.fuel.set near 100.
• Check the dial's FUEL line, or GetFuelState from a script.
• An AV is never cut (USAGE = 0).

No fuel station on the map: stations are disabled until surveyed

Every shipped station is a placeholder at 0, 0, 0. The log says:

[fuel] 5 station(s) disabled until surveyed (/opx.fuel.capture): ...
[fuel] no station is open: every tank still burns, and only a can or staff fills one

• Survey each station with /opx.fuel.capture, paste the lines into config/fuel.lua, restart. /opx.fuel.stations lists what is open.
• A station with a single unsurveyed pump stays disabled whole.

[fuel] config: STATIONS.<key> ...

A station was refused for its shape (no PUMPS, over MAX_PUMPS, a non-finite coordinate, a bad BUCKET or LABEL). Fix the block.

Tanks empty twice as fast

Both this module and open77_fuel burn. Set STAND_DOWN = true (the default); /opx.fuel.stations should end burning: open77_fuel.

Staff immunity does nothing

opx.admin.immune, opx.admin.override and opx.admin.vehicle.anywhere are raw rights, not command.* names: a role granted command.* does not hold them.

• Add each one to the role in acl.jsonc explicitly. See Raw rights.
• A typed vehicle id answering vehicle_out_of_reach: grant opx.admin.vehicle.anywhere or raise VEHICLES.REACH.

Emotes with a nearby player missing

[animations] Open77.playerInteractions is unavailable ...

No emote with a nearby player is offered.

• Start open77_player_interactions and keep players.interactions.control in the manifest.

[animations] Open77.animations.list is unavailable; only the written catalogue is offered

open77_animations is missing or the build is old: only the 15 written animations are offered.

Holocalls refused with notContact

Calls go to contacts only. Players swap contacts face to face first; offering it again to the same player waits 30 s (contactTooSoon). See calls.

Names and identity

I don't see names above heads

Intended since PR #93: never a name to a stranger. Every remote player's plate is hidden (no character name, no account gamertag). Chat lines are signed Player #12, the give list says where a person stands (To your left · 1.2 m), and a holocall names only your contacts. See Privacy.

• Staff see names with /opx.admin.self.tags (grant command.opx.admin.self.tags).
• [character] this client has no Open77.nameplates: remote plates cannot be hidden and will show the account name: the client build has no plate API; update the client.

My resource reads Open77.state.player(id).name and gets nil

The player state bag is empty since PR #93. Read the local player with the client export GetPlayerData, and other players on the server with the server exports. See Writing a resource.

A call shows "Unknown caller"

That person is not in your contacts. Swap contacts face to face; from then on their name shows on cards, toasts and recent calls.

Keys and screens

E does nothing next to a garage and a door

E did something, for the nearer spot: when two places that use E are both in reach (a garage beside a door, a lift beside a teleport), only the nearer one acts, and only its row is drawn on the key strip. Step closer to the one you want. A lockpick under way holds E for its door. The order is KEY_PRIORITY; see One press, one owner.

X put the crate down but did not hang up the call

One press, one action. X goes to: a cancelable progress bar, then a ringing call (decline), your outgoing call (withdraw), a carried crate, your emote, and last a call in progress (hang up). Rebind one of them in the pause menu to keep both on separate keys.

Y does not peek the hotbar

While a call rings, Y answers it and the peek stays silent. Intended.

Escape closed only one screen

Intended since PR #95: Escape closes the top layer only (the screen opened last), and inside a submenu it goes back one level.

A click on an eye row only changed it to "Confirm: …"

A danger row asks for a second click within 4 s. A resource that wants one click sets confirm = false on the row (AddTarget).

"Too far" at the edge of a marker

The server allows REACH_SLACK (1 m) beyond the radius the client draws. Raise it (0–4) if players with high latency are still refused.

Server rules players notice

Since PRs #99 and #101 the server decides these, whatever a client sends.

My hunger doesn't change from a client script

Intended since PR #101: the server owns the needs. The client contract and the client export GetNeeds are read only, and the old push event is gone, so a value set on the client goes nowhere (the next server update overwrites it). Move a need from your resource's server side with the exports AddNeeds / SetNeeds (add your resource to SERVER.EXPORTS.WRITERS), or give the item a USE.STATUS. Staff use /opx.needs.set. See needs.

I can't chat on the character screen

That message was not sent: you speak once your character is in the city. (chat.notLoaded). Intended since PR #101: a line goes to every player, so only a connection with a loaded character may send one. Staff holding STAFF_PERMISSION (command.opx.admin by default) still can; the console always can. Typed / commands are not affected.

A share code says I'm not in a fitting room

Since PR #101 an outfit code is redeemed only inside a clothing shop's fitting room: stand at the shop's counter, open Try clothes on, then type the code in the room. Away from a shop it answers shops.redeemAtShop; at the counter without the room open, shops.redeemInRoom (Open the fitting room first…). The pieces are billed at that shop's prices when you Save; Cancel costs nothing. See Saved outfits and share codes.

Give says "Waiting for an answer"

Since PR #101 a give is an offer: the other player gets an Accept / Refuse card, and nothing moves until they accept. The offer stands 15 s; then you read Your offer of … was not answered. While one is open, a second give answers give_pending (yours) or give_busy (theirs). If they accept but you moved the stack, walked away or their bag is full, the give fails and you are told. See Give and drop.

"Not while you are down"

Since PR #99 a downed player cannot use a garage, dealer, shop, fitting room, crafting bench, armoury chest or car key, or open a stash: error.incapacitated, shops.downed, crafting.downed, gunsmith.dead or dead. Get revived first.

Reporting a problem

• Something only a live server can show (doors, duo emotes, the loading cover, the give list, medical items, fitting-room prices): follow the matching section of the framework's in-game checklist, which lists the steps, the expected result, the log lines to watch and what to put in the issue.
• A limit of the Open77 platform itself (prop aliases, the loading-state API, setModel on the server, open77_doors without open77_elevators): see platform requests for the current fallback before reporting it.

Useful commands

See the diagnostics module.