RedM Guidebook Troubleshooting

Run /almanac_debug first. It prints a self-check to the server console — what bound, what the database holds, whether the overlay is built, what you personally may do, and a list of anything that is legal but almost certainly not what you meant.

Most of the sections below are answered by it in one line.

If it does not, turn the traces on and reproduce the fault — every line is tagged with the part of the resource it came from:

-- local/overrides.lua
RmGuidebook.Local = { debug = { enabled = true } }

Each channel can be silenced on its own once you know which one you want:

RmGuidebook.Local = {
    debug = { enabled = true, log = { bridge = true, ledger = true, shelf = false,
                                      field = false, hud = false, link = false, press = true } },
}

It bound the wrong framework, or none

[rm_guidebook] framework: standalone

…on a server that has one. The bridge probes for vorp_core, then rsg-core, then redem_roleplay, and takes the first that is started. If yours starts after this resource, it will not be found.

Fix it by naming it, which skips the probe entirely:

RmGuidebook.Local = { bridge = { framework = 'vorp' } }

vorp, rsg, redemrp and standalone are the four names.

If it is named and still lands on standalone, the adapter's bind() failed — the framework is running but its export did not answer. The console says so with the reason.

The almanac is empty on a fresh install

Either the database never answered, or the seed is off.

[rm_guidebook] the database never answered; the almanac cannot open

means oxmysql could not create the tables in ten tries. Check that oxmysql itself started and that its connection string is right — the same check that would break your framework.

If there is no such line and the almanac is still empty, seed = { demo = false } is set, or the tables already existed and were empty. Open the press and write a chapter, or run /almanac_demo.

Staff is refused

/press says the press is not yours to run. Work through the three checks in order.

The ACE. The commonest cause is the principal, not the ace:

add_ace group.admin rm_guidebook.press allow
add_principal identifier.license:XXXXXXXXXXXXXXXX group.admin

Both lines are needed. The second one is the one people forget.

The group. On VORP the group lives in two places and they routinely disagree — /addGroup writes one and /addGroupChar writes the other. Both are read here, so if neither says admin that is why. On RSG there are no groups at all and this check does nothing.

The framework's own call. Only RSG answers one. god and admin are both accepted.

Turn on the press trace and the refusal is logged with the name of whoever was refused.

The key does nothing

It is a real key mapping, so a player may already have F7 bound to something else — the game's own key settings will show the conflict.

/almanac always works, and is worth trying first to tell "the key is not bound" apart from "the almanac will not open".

The overlay is blank, or does not open

The build is missing. web/dist/index.html has to exist.

On the escrow edition it always does — web/dist ships built. On the Open Source edition, after changing web/src/:

cd web && npm install && npm run build

A resource restart is not enough after a rebuild

CEF caches aggressively. Restart the client, or /restart rm_guidebook and rejoin.

If the build exists and the overlay is still blank, open the F8 console and look for a script error. /almanac_debug says outright whether the built file is there.

A signpost has no prompt

In order of likelihood:

Cause
It is not shown	shown off hides it from everyone including staff. It is what an author switches off while placing one
Your job may not see it	Restricted signposts are not drawn at all. If you are staff and expected to see it, check access.staffSeesAll
You are further away than you think	The prompt appears within signpost.reach, two metres by default. The floating title has its own, larger reach — so seeing the title without a prompt is normal
An overlay is open	Prompts are hidden while the almanac or press is up, deliberately: a prompt behind a NUI is one the player can trigger through the page they are reading

A signpost has no blip

The blip is a separate switch. Check Map blip is on in the press.

If it is on and nothing draws, the sprite name is probably not one the game knows — which draws an empty square rather than an error. Pick one from the list in the press rather than typing one: every name offered there was read out of the game's own catalogue.

The marker is in the ground, or floating

Markers are drawn at the signpost's position plus signpost.markerLift, which ships at -1.0. That is right for a cylinder at a standing player's feet and wrong for most other shapes.

RmGuidebook.Local = { signpost = { markerLift = 0.0 } }

Everyone can see a page they should not

Check three things, in order:

1. access.enabled is true in your settings.
2. The chapter and the entry both have the access block set. An open chapter containing a restricted entry still hides the entry — but the chapter is visible.
3. You are not testing as staff. access.staffSeesAll defaults to true. Turn it off, or test on a second account.

A page vanished

Check whether someone struck it, and check the access block — a job change can make a page you could read yesterday invisible today.

/almanac_debug lists what the database actually holds, which settles it either way.

Search says nothing was found, but the words are there

Three reasons, all deliberate:

• Hidden entries are not searchable. They are reachable by slug and by signpost, but not discoverable. That is the difference between unlisted and secret.
• Restricted entries are not searchable by anyone who could not read them.
• The query is matched against the text, not the markup. Searching for <strong> finds nothing, which is the point.

"Someone else wrote this leaf just now"

Working as intended. Two people had the same entry open, the other one saved first, and yours was refused rather than overwriting theirs.

The editor has been reloaded with what is actually stored. Make your change again and save.

The text is in the wrong language

RmGuidebook.Local = { language = 'de' }

en, de, es and fr ship. A key missing from a translation falls back to English rather than showing a raw key.

If it is still wrong, the locale file is probably not named for the code you set — language = 'pt' looks for RmGuidebook.Phrases.pt.

Nothing reaches Discord

log = { webhook = '...' } has to be set. If it is, turn the bridge trace on — the status Discord answered with is printed, and a 401 or 404 means the URL is wrong or was deleted.

Logging never takes the press down with it: a webhook that refuses costs a line in the console and nothing else.

SCRIPT ERROR: native <hash>: exception at address ...

Not a Lua error — an access violation inside the game process, which is why no pcall catches it and why the message names an address rather than a line.

It means a native was called through Citizen.InvokeNative when its signature takes a pointer: REMOVE_BLIP(Blip*), DELETE_ENTITY(Entity*) and friends. Those expect the address of the handle, and the CFX wrapper — RemoveBlip(blip) — exists precisely to allocate it, pass it and read the value back. Handed the bare handle, the game dereferences an integer.

tools/audit.py fails the build if the hash of a known pointer-taking native appears anywhere in the resource, so this should not come back. If you hit it with a hash the audit does not know, paste the whole line into Discord — a hash is specific enough to identify in minutes.

Something changed behind its back

/almanac_resync

Re-reads everything from the database and pushes it to everyone, which fixes any state that has drifted — a row edited by hand, a backup restored, a second server writing to the same database.

It also re-reads the job list, so a job added since start-up appears in the access picker without a restart.

What to send when you ask for help

Send
The output of /almanac_debug	Answers most of this page in one go
Which framework, and which edition	EDITION.txt says which edition in its first line
What you expected, and what happened instead
Your local/overrides.lua	Remove log.webhook first — it is a credential

If you have modified an Open Source edition, say so and keep a clean copy. Comparing against one is the quickest way to find out which half is at fault.

On the Open Source edition, three checks run outside the game:

node tools/simulate.cjs   # the shared rules
node tools/harness.cjs    # the whole server half, headless, with debug on
python tools/audit.py     # Lua, overlay and languages against each other

If any is red, that is your answer before you look any further — and the failing check names what broke.

On the escrow edition these are not in your zip, and you do not need them: the escrowed code is the code those checks were green against before it shipped. /almanac_debug is your equivalent, and it sees things they cannot — your database, your framework, your settings.