Skip to main content
This guide covers common errors and issues you may encounter when using Hedis, along with their solutions.

​
Installation Issues

​
Go Build Failures

Symptom: 
go: module not found
build failed
Causes:
  • Missing dependencies
  • Incorrect Go version
  • Module cache corruption
Solution: 
# Verify Go version (requires 1.23+)
go version

# Clean module cache
go clean -modcache

# Download dependencies
cd go/hermes-decompiler
go mod download
go mod tidy

# Rebuild
go build -o hermes-decompiler .

​
Node.js Dependency Errors

Symptom: 
npm ERR! code ENOENT
npm ERR! syscall open
Solution: 
# Clean npm cache
npm cache clean --force

# Reinstall dependencies
cd js/dependency-resolver
rm -rf node_modules package-lock.json
npm install

cd ../get-packages
rm -rf node_modules package-lock.json
npm install

​
MongoDB Connection Errors

​
Connection Refused

Symptom: 
MONGO_CONNECTION_STRING is not set
exit status 1
Solution:
  1. Verify .env file exists:
ls -la go/hermes-decompiler/.env
  1. Check connection string format:
# .env file
MONGO_CONNECTION_STRING=mongodb://localhost:27017
  1. Test MongoDB connection:
mongosh "$MONGO_CONNECTION_STRING"
  1. Start MongoDB if not running:
# Docker
docker start hedis-mongo

# Or start new container
docker run -d -p 27017:27017 --name hedis-mongo mongo:latest

# Local installation
mongod --dbpath /path/to/data

​
Authentication Failed

Symptom: 
failed to connect to MongoDB: authentication failed
Solution: Update connection string with credentials: 
# .env file
MONGO_CONNECTION_STRING=mongodb://username:password@localhost:27017/hedis?authSource=admin
Test authentication: 
mongosh "mongodb://username:password@localhost:27017/hedis?authSource=admin"

​
Database Not Found

Symptom: 
database "hedis" does not exist
Solution: MongoDB creates databases on first write. Run database initialization: 
cd go/hermes-decompiler
./hermes-decompiler maintain-database -b
Or verify database name in .env: 
MONGO_DB_NAME=hedis

​
Disassembly Errors

​
Unsupported Bytecode Version

Symptom: 
Warning: This file uses a future Hermes bytecode format, which is not yet supported [97].
Cause: HBC file uses a bytecode version newer than v96. Solution:
  1. Check file bytecode version:
hexdump -C bundle.hbc | head -n 5
Look for version number after magic bytes 1F 19 03 C1 03 BC 1F C6.
  1. Add support for the new version:
See Contributing: Adding Bytecode Support.
  1. Fallback to older parser:
Hedis automatically uses the closest older parser version (e.g., v97 uses v96 parser). This may work if opcodes haven’t changed significantly.

​
Opcode Not Implemented

Symptom: 
opcode 0xAB is not implemented
Cause: Bytecode contains an opcode not defined in the selected parser version. Solution:
  1. Verify bytecode version matches parser:
# Check which parser is being used
go run main.go disassemble -i bundle.hbc -o output.txt
  1. Regenerate opcode definitions:
cd go/hermes-decompiler
sh pkg/utils/download_all.sh
go run main.go genopcodes
  1. File a bug report if the issue persists with the correct parser version.

​
Invalid HBC File

Symptom: 
failed to read HBC header: unexpected EOF
invalid magic number
Cause: File is not a valid Hermes bytecode file or is corrupted. Solution:
  1. Verify file is HBC:
file bundle.hbc
hexdump -C bundle.hbc | head -n 5
Valid HBC files start with: 1F 19 03 C1 03 BC 1F C6
  1. Extract HBC from IPA:
If analyzing an iOS app, extract the HBC bundle first: 
unzip app.ipa
find Payload -name "*.hbc"
  1. Recompile JavaScript:
If you have the source: 
hermesc -emit-binary -out bundle.hbc index.js

​
Analysis Errors

​
No Matches Found

Symptom: 
Analysis complete: 0 packages matched
Causes:
  • Empty or outdated database
  • App uses a different React Native version
  • Code is heavily obfuscated
Solution:
  1. Check database population:
mongosh "$MONGO_CONNECTION_STRING"
use hedis
db.hashes.countDocuments()
  1. Build database fingerprints:
cd go/hermes-decompiler
./hermes-decompiler maintain-database -b  # Generate baselines
./hermes-decompiler maintain-database -p  # Process packages
  1. Enable fuzzy matching:
./hermes-decompiler analyze -b bundle.hbc -f -c 0.7
Lower confidence threshold to 0.7 for more matches.
  1. Check React Native version compatibility:
Hedis database covers RN versions 0.69–0.79. Apps using different versions may not match.

​
Low Confidence Matches

Symptom: 
Matched package "[email protected]" with confidence 0.45
Cause: Code may be partially modified, obfuscated, or use different build settings. Solution:
  1. Adjust confidence threshold:
./hermes-decompiler analyze -b bundle.hbc -f -c 0.4
  1. Use specific package comparison:
./hermes-decompiler analyze -s \
  -p lodash.hbc \
  -a app-bundle.hbc
  1. Review match details:
Check which hash types matched:
  • Structural matches indicate same control flow
  • Content IR1 matches indicate same string literals
  • Content IR2 matches indicate same API usage

​
Memory Issues

Symptom: 
fatal error: out of memory
runtime: out of memory
Cause: Large HBC files or processing many packages simultaneously. Solution:
  1. Increase available memory:
# Docker
docker run -m 8g hedis analyze -b bundle.hbc

# Kubernetes
resources:
  limits:
    memory: 8Gi
  1. Process packages in smaller batches:
Edit batch size in pkg/pipeline/batcher.go: 
const DefaultBatchSize = 50  // Reduce from 100
  1. Enable swap space (Linux):
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

​
Pipeline Errors

​
Package Processing Failures

Symptom: 
Package group lodash had 5 errors out of 10 versions
all packages failed for RN version rn069: 50 errors
Causes:
  • npm install failures
  • Hermes compilation errors
  • Missing dependencies
Solution:
  1. Check pipeline progress:
cat go/hermes-decompiler/pipeline_progress.json
  1. Resume from failure:
./hermes-decompiler maintain-database -p
The pipeline automatically resumes from pipeline_progress.json.
  1. Check failed package logs:
jq '.rn_environments["rn069"].failed_packages' pipeline_progress.json
  1. Manually test package:
cd pipeline/react-natives/rn069
npm install [email protected]
npm run build

​
Hermes Compiler Not Found

Symptom: 
failed to execute hermesc: no such file or directory
Cause: OS_HERMES environment variable not set or incorrect. Solution:
  1. Set OS_HERMES in .env:
# macOS
OS_HERMES=osx-bin

# Linux
OS_HERMES=linux64-bin
  1. Verify Hermes binary exists:
ls -la pipeline/react-natives/rn069/node_modules/hermes-engine/$OS_HERMES/hermesc
  1. Reinstall React Native environment:
cd pipeline/react-natives/rn069
rm -rf node_modules
npm install

​
Metro Bundler Errors

Symptom: 
error: bundling failed
TransformError: Cannot find module 'lodash'
Cause: Package not properly installed or Metro cache corruption. Solution:
  1. Clear Metro cache:
cd pipeline/react-natives/rn069
rm -rf .metro-cache
npm run build
  1. Reset environment:
cd pipeline/react-natives/rn069
rm -rf node_modules .metro-cache
npm install
npm run build

​
GitHub API Errors

​
Rate Limiting

Symptom: 
GitHub API returned status 403: rate limit exceeded
Cause: GitHub API rate limit reached (60 requests/hour without token, 5000/hour with token). Solution:
  1. Set GITHUB_TOKEN:
# .env file
GITHUB_TOKEN=ghp_your_token_here
  1. Check rate limit status:
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/rate_limit
  1. Wait for reset:
Rate limits reset hourly. Check X-RateLimit-Reset header.

​
Authentication Failed

Symptom: 
GITHUB_TOKEN environment variable is not set
Solution:
  1. Generate GitHub token:
Go to GitHub Settings > Developer settings > Personal access tokens
  1. Set token with required scope:
# Requires 'public_repo' scope
GITHUB_TOKEN=ghp_abcdefghijklmnopqrstuvwxyz1234567890
  1. Verify token:
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/user

​
Performance Issues

​
Slow Disassembly

Symptom: Disassembly takes >5 minutes for a large HBC file. Solution:
  1. Disable unnecessary output:
# Only output functions, skip strings and objects
./hermes-decompiler disassemble -i bundle.hbc -f
  1. Use binary output mode (if available):
./hermes-decompiler disassemble -i bundle.hbc -o output.bin --binary
  1. Process in parallel (for multiple files):
find . -name "*.hbc" | xargs -P 4 -I {} \
  ./hermes-decompiler disassemble -i {} -o {}.txt

​
Slow Analysis

Symptom: Analysis takes >30 minutes. Cause: Fuzzy matching scans entire database. Solution:
  1. Disable fuzzy matching:
./hermes-decompiler analyze -b bundle.hbc
  1. Increase MongoDB indexes:
mongosh "$MONGO_CONNECTION_STRING"
use hedis
db.hashes.createIndex({ "structural_hash": 1 })
db.hashes.createIndex({ "content_ir1_hash": 1 })
db.hashes.createIndex({ "content_ir2_hash": 1 })
  1. Filter by React Native version:
If you know the app’s RN version, query only that version’s hashes.

​
Getting More Help

If your issue isn’t covered here:
  1. Check GitHub Issues: github.com/your-org/hedis/issues
  2. Enable debug logging:
export DEBUG=1
./hermes-decompiler analyze -b bundle.hbc
  1. File a bug report with:
    • Hedis version (./hermes-decompiler --version)
    • Operating system and version
    • Full error message and stack trace
    • Steps to reproduce
    • Sample HBC file (if possible)

Build docs developers (and LLMs) love

Get started for freeTalk to us