Troubleshooting

Troubleshooting

Organized by symptom. Each entry states what you would observe, the usual cause, and how to resolve it.

Contents

• First steps
• Installation problems
• Ghidra problems
• Stage and tool problems
• Output problems
• Performance problems
• Dynamic analysis problems
• Getting help

First steps

Three commands resolve or diagnose most problems.

Verify the installation.

sudo ./install-retoolkit.sh --verify

Produces a PASS/FAIL table for every tool without changing anything. An installer can complete without obvious error while leaving specific tools unusable, and this is how you find out.

Read the logs. Installer problems are logged per phase to /var/log/retoolkit/. Analysis problems are logged per tool under <outdir>/<target>/90-logs/.

Turn up the log level.

analyze-binaries.sh -t sample.exe -o ./out --log-level=debug

Skip reasons are logged at debug level, which is usually what you want when a stage produced nothing and you cannot tell why.

Installation problems

Packages report as failed during the apt phase

Usual cause: Expected behavior, not a failure. Several tools are not available through apt on some distributions and are recovered by source builds in LAYER 2H, which runs later.

Resolution: Wait for the post-LAYER-2H summary before treating an apt-stage message as a problem. The summary distinguishes packages that were recovered from those genuinely unresolved. Only the latter need attention.

The installer appears to hang

Usual cause: A package triggering an interactive prompt, most often a service restart prompt during a Docker install.

Resolution: The installer forces non-interactive package operations, so this should not occur on a current version. If it does, confirm you are on 3.7.3 or later. Check the active phase log in /var/log/retoolkit/ to see what it was doing when it stopped.

The install fails partway through

Usual cause: A transient network failure, or an incompatibility with the distribution's current package state.

Resolution: Re-run the installer. It is idempotent, so existing components are detected and skipped, and only what did not succeed is retried. Read the phase log first to distinguish a transient problem from a real incompatibility, since re-running will not fix the latter.

A source build fails

Usual cause: A missing build dependency, or an upstream change.

Resolution: The build log in /var/log/retoolkit/ names the failure. Confirm LAYER 1 completed, since source builds depend on the toolchain it installs. To retry after fixing the cause:

sudo ./install-retoolkit.sh --force --skip-apt --skip-dotnet --skip-ghidra

YARA rules fail to compile with duplicate identifier errors

Usual cause: Rule identifiers must be unique across a whole rule set, and independently maintained rule files collide.

Resolution: The installer builds a deduplicated master index, so this should not occur with the provisioned rules. If you supplied your own rule directory, point --yara-rules at a deduplicated master file rather than at a directory.

Ghidra problems

Ghidra analysis times out

Usual cause: A large or complex binary exceeding the per-file timeout.

Resolution: Raise the timeout and the heap.

analyze-binaries.sh -t large.exe -o ./out -T 7200 -H 8G

If it still does not complete, --no-ghidra lets the rest of the pipeline proceed. You lose function inventory, decompilation, and cross-references, and the summary features that depend on them.

Ghidra is not found

Usual cause: Installed outside the searched locations.

Resolution: Discovery checks GHIDRA_INSTALL, GHIDRA_INSTALL_DIR, /opt/ghidra, /opt/ghidra_*_PUBLIC, and /usr/share/ghidra. Point at it explicitly:

analyze-binaries.sh -t sample.exe -o ./out -g /path/to/ghidra

The Ghidra dump is empty or the decompilation panel is blank

Usual cause: Ghidra ran but the postscript did not produce parseable output.

Resolution: Check 30-ghidra/ for the script log. An empty log suggests the script never executed; a log that starts and stops suggests it failed partway. tools/ghidra-diagnostic.py exercises the Ghidra path in isolation.

The Ghidra GUI stops working after installation

Usual cause: Ghidrathon can break the GUI on some Java 21 builds.

Resolution: Ghidrathon is not installed unless you passed --install-ghidrathon. If you did, remove it. Command-line analysis does not need it.

Stage and tool problems

A stage produced no output

Usual cause: One of four different things, which the logs distinguish: the stage was skipped, the tool was not installed, the tool timed out, or the tool ran and found nothing.

Resolution: These are not equivalent and should not be treated as such.

# Which stages ran, were skipped, or failed
cat out/target.exe/90-logs/*ledger* 2>/dev/null

# Why a stage skipped
analyze-binaries.sh -t sample.exe -o ./out --log-level=debug 2>&1 | grep -i skip

Then confirm the tool exists with --verify, and check the environment for an exported skip control that is silently disabling it:

env | grep -E '^(SKIP_|ENABLE_)'

A tool reports success but its output is unusable

Usual cause: An invocation using an option the installed tool version does not recognize. The tool prints usage text and exits zero, so the exit status suggests success while the parser extracts nothing.

Resolution: RE-Toolkit validates output shape specifically to catch this class, and records it as a silent failure rather than a success. If you see it recorded, the tool version and the expected invocation have diverged, which is worth reporting as a bug with the tool version included.

A tool is reported as missing after a successful install

Usual cause: The tool failed to install while the overall run reported success, or it is not on the path.

Resolution:

sudo ./install-retoolkit.sh --verify

If the tool shows FAIL, reinstall that component with --force plus skip flags for everything else. If it shows PASS but the stage still cannot find it, the issue is path resolution rather than installation.

Analysis stops on one target in a batch

Usual cause: A stage calling exit rather than returning, which terminates the driver.

Resolution: This is a bug in the stage. Stages must return so the driver retains control. Report it with the target type and the stage name. As a workaround, disable the stage and re-run.

Output problems

The report is missing sections

Usual cause: The stages that populate those sections did not run.

Resolution: Check the tool coverage panel in the report, which states what ran and what did not. A section is absent because its data source is absent, not because rendering failed.

Visualizations are empty

Usual cause: The visualization ran but its input data was missing.

Resolution: Empty visualizations degrade with explanatory text rather than failing, so the text usually names the missing input. Most often the upstream stage was skipped. Function-complexity and cross-reference visualizations depend on Ghidra, so --no-ghidra empties them.

A target was skipped entirely

Usual cause: It was already analyzed. Targets are skipped when output already exists for their recorded hash.

Resolution:

analyze-binaries.sh -t sample.exe -o ./out --overwrite

Indicators contain obvious noise

Usual cause: Indicator extraction reads output other stages produced, which includes tool self-reports and version strings that resemble indicators.

Resolution: Indicators are classified three ways: behavioral, infrastructure, and dropped noise. The report shows behavioral indicators first and tags infrastructure separately. If genuine noise is reaching the behavioral set, that is a classifier bug worth reporting with the specific value.

Performance problems

A run is very slow

Usual cause: Ghidra, deep radare2 analysis, or a large binary.

Resolution: In order of effect:

# Skip the slowest stage
analyze-binaries.sh -t sample.exe -o ./out --no-ghidra

# Parallelize a batch
analyze-binaries.sh -t ./samples -o ./out -j 4

# Filter the walk before type detection
analyze-binaries.sh -t ./tree -o ./out --include-ext=exe,dll

# Lower the per-tool ceiling for triage
analyze-binaries.sh -t sample.exe -o ./out --tool-timeout 120

Parallelism helps batches rather than a single binary, since each worker takes one target end to end. Note that --deep-analysis significantly increases run time and should not be on for routine work.

Memory exhaustion

Usual cause: Ghidra's JVM heap, or several parallel workers each running memory-hungry tools.

Resolution: Reduce -j, or lower -H if the host cannot support the heap. Raising the heap helps Ghidra complete but increases per-worker memory, so the two settings interact.

Dynamic analysis problems

Dynamic tiers are skipped

Usual cause: Missing --allow-real-execution, an inapplicable target type, or a missing prerequisite.

Resolution: Each tier records its own skip reason. Tier 1 needs no consent flag; Tiers 2 through 4 do. Tier 2 applies to ELF targets only. Tier 3 requires --with-docker at install time. Tier 4 requires a cuckoo deployment you built yourself.

Emulation stops early

Usual cause: The target used an API the emulator does not implement.

Resolution: Expected, and partial results are still useful. A truncated trace showing the first several calls often answers the question. If you need complete behavior, escalate to a real-execution tier inside a disposable VM.

Emulation fails to start

Usual cause: The root filesystem for the target platform is missing.

Resolution: Emulation needs a platform root filesystem, provisioned into /opt/qiling-rootfs/. Confirm it exists and contains the architecture directory matching your target.

The sample did nothing observable

Usual cause: Several possibilities that are not equivalent: the sample is benign, it detected the analysis environment, it failed to run, or it waited longer than the timeout allowed.

Resolution: Check the tier status and any error output first. Then consider extending --dynamic-timeout, since delayed execution is a common evasion. Benign observed behavior is not proof of a benign sample.

Getting help

Before opening an issue, gather:

• The exact command you ran
• The output of analyze-binaries.sh --version
• Your distribution and version
• The target's type from file -b
• The relevant stage log from 90-logs/, or the phase log from /var/log/retoolkit/

Redact anything sensitive, including paths that identify a case or a customer.

Open a bug report. For a suspected vulnerability in RE-Toolkit itself, do not open a public issue; follow SECURITY.md.