User Guide Troubleshooting

Troubleshooting

Prev: Using Native rqp Packages | Up: User Guide | Next: Extending ReqPack

This page collects common ReqPack failure modes, what they usually mean, and fastest fix.

First Checks

Before deep debugging, check these first:

1. confirm target system/plugin name is right
2. confirm plugin bundle has metadata.json, reqpack.lua, run.lua, scripts/install.lua, scripts/remove.lua
3. confirm local file install can be mapped to system, or pass explicit system
4. confirm host metadata is fresh if plugin branches on OS/CPU state

Useful command:

rqp host refresh

That refreshes cached host snapshot used by plugins via context.host and reqpack.host.

Local File Install Fails

Common errors:

cannot determine system for local target: <path>
Use: rqp install <system> <path>

or:

no plugin found for file extension '.xyz': <path>
Use: rqp install <system> <path>

Meaning:

• ReqPack could not infer system from local path
• or no plugin declares matching plugin.fileExtensions

Fix:

• run rqp install <system> <path> explicitly
• or add correct plugin.fileExtensions to plugin bundle

Plugin Does Not Load

Common errors:

[Lua API Error] plugin table is required.
[Lua API Error] getMissingPackages is required.
plugin load failed

Meaning:

• run.lua did not define global plugin table
• required methods are missing
• plugin.init() returned failure
• or thin-layer trust / hash checks rejected plugin during load

Fix:

• verify required Lua contract in Writing Lua Plugins
• verify plugin.init() does not fail at startup
• if security.requireThinLayer = true, verify runtime getSecurityMetadata() matches registry record

Proxy Resolution Fails

Common errors:

proxy resolution depth exceeded for '<system>'
proxy resolution cycle detected
proxy '<system>' could not resolve request
proxy '<system>' resolved to itself
proxy '<system>' resolved to unknown target '<target>'
proxy '<system>' returned both packages and localPath

Meaning:

• proxy chain loops or is too deep
• resolveProxyRequest() returned nil
• plugin resolved to invalid/self target
• plugin returned illegal shape

Fix:

• keep proxy chain short
• return exactly one of packages or localPath
• keep target inside configured planner.proxies.<system>.targets
• do not return current system again

Thin-layer Exec Denied

Common errors:

execution policy denied for plugin '<id>': shell command requires capability 'exec'.
execution policy denied for plugin '<id>': command requests privilege escalation but privilegeLevel is 'none'.
execution policy denied for plugin '<id>': command writes outside declared writeScopes ('<path>').

Meaning:

• plugin tried to execute shell command without exec capability
• command used sudo or doas without privilegeLevel = "sudo"
• command writes outside declared writeScopes

Fix:

• update plugin.getSecurityMetadata() honestly
• keep plugin thin and restrict writes to declared scopes
• remember runtime exec enforcement needs both:
  • security.requireThinLayer = true
  • execution.checkVirtualFileSystemWrite = true

Exec Rules Fail To Parse

Common errors:

rules.rules[1].source must be 'line' or 'screen'.
rules.rules[1] is missing field 'regex'.
rules.rules[1] is missing field 'actions'.

Meaning:

• exec-rules table shape is invalid
• top-level or rule fields use wrong keys/types

Fix:

• check schema in Writing Lua Plugins
• make rules contiguous array-style Lua table
• use only line or screen sources

rqp pack Fails

Common errors:

pack project is missing metadata.json
pack project is missing reqpack.lua
pack input is ambiguous: use either payload-tree/ or --payload-dir, not both
pack input is incomplete: payload/ and hashes/ must both be present
metadata.payload requires payload files or payload tree
output file already exists: <path>
Use --force to overwrite.

Meaning:

• package project is incomplete
• payload source modes are mixed illegally
• output already exists

Fix:

• keep exactly one payload mode
• provide both payload/ and hashes/ when using prebuilt payload
• use --force for overwrite in non-interactive runs
• see Building rqp Packages and Repositories

Native .rqp Install Fails On Host Compatibility

Common errors:

package architecture does not match host
rqp missing install hook
payload sha256 mismatch
payload archive missing

Meaning:

• package metadata does not fit current host
• package is malformed
• payload file/hash is missing or corrupted

Fix:

• rebuild package with correct architecture or use noarch only when really valid
• keep hooks.install present in package reqpack.lua
• regenerate payload and hashes/payload.sha256

test-plugin Fails

Common errors:

no fakeExec rule matched command: <command>
commands did not match expectation
events did not match expectation
resultCount mismatch

Meaning:

• hermetic fake command table did not match plugin output
• plugin behavior changed and case expectations are stale

Fix:

• make fakeExec.match substrings specific and correct
• update case expect section to actual intended behavior
• use Testing Lua Plugins for exact case schema

Snapshot Output Is Empty Or Incomplete

Meaning usually one of these:

• history.trackInstalled disabled
• packages were not installed through ReqPack-managed flows
• installed-state tracking has not been refreshed yet

Fix:

• enable history.trackInstalled = true
• re-run installs through ReqPack
• read Configuration and Data, State, and Trust

Plugin Sees Wrong OS / CPU / Core Count

Yes, ReqPack has host-introspection API. Lua plugins can read:

• context.host.os.*
• context.host.cpu.arch
• context.host.cpu.vendor
• context.host.cpu.model
• context.host.cpu.logicalCores
• context.host.cpu.physicalCores
• context.host.memory.totalBytes
• context.host.memory.availableBytes
• context.host.gpus
• context.host.storage.mounts

If values look stale:

rqp host refresh

Important runtime difference:

• context.host is per-call snapshot and should be preferred
• reqpack.host is bridge-global snapshot created when plugin was constructed

Full field list is documented in Writing Lua Plugins.

Related Pages

• Getting Started
• Configuration
• Writing Lua Plugins
• Testing Lua Plugins

Prev: Using Native rqp Packages | Up: User Guide | Next: Extending ReqPack