FAQ

“file not found” when running examples

The rootfs directory is hosted in a separate repo. Fetch it:

1git submodule update --init --recursive

Or clone from https://github.com/qilingframework/rootfs.

How to run MS-DOS binaries (MBR, COM, EXE)

File extension must match the format:

• filename.DOS_EXE
• filename.DOS_COM
• filename.DOS_MBR

Syscall or API not implemented

When a required syscall is missing, options:

1. Implement it and contribute (see extension guide)
2. Reuse a similar syscall — e.g. vfork can often share fork implementation
3. Use ql.os.set_syscall() or ql.os.set_api() to provide a custom stub (see hijack guide)

Map the syscall to the arch in qiling/os/linux/<arch>.py.

UC_ERR_FETCH_UNMAPPED / UC_ERR_WRITE_UNMAPPED

Not a bug. Common causes:

1. Unimplemented syscall/API — the binary called something Qiling doesn’t handle yet
2. Missing environment requirement — e.g. firmware needs br0 interface; use ql.patch() to bypass
3. Missing files — config file or library absent from rootfs

Enable debug/disasm mode to pinpoint the failing instruction:

1ql = Qiling(..., verbose=QL_VERBOSE.DEBUG)

GDB connection timeout: “Remote replied unexpectedly to ‘vMustReplyEmpty’: timeout”

The emulation script is running too slowly for GDB’s default timeout. Fix:

1(gdb) set remotetimeout 100

If that doesn’t help, enable remote debug logging:

1(gdb) set debug remote 1

AttributeError: ‘NoneType’ object has no attribute ‘cur_thread’

Multithread is disabled by default. Enable it:

1ql = Qiling(..., multithread=True)
2# or with qltool:
3./qltool run ... --multithread

Windows API: do I need to implement both FunctionA and FunctionW?

No. Use functools wraps to share implementation. Example — OpenMutexA delegates to OpenMutexW.__wrapped__:

1@winsdkapi(cc=STDCALL, dllname=dllname)
2def hook_OpenMutexA(ql, address, params):
3    return hook_OpenMutexW.__wrapped__(ql, address, params)