Troubleshooting
Find the message, then apply the fix. Unless a row says otherwise, every message below
was reproduced with AsmFoundation.Sdk 0.1.0, NASM 3.02 and ld.lld 23.1.5, and is
written with the current property names. The ASM0003, ASM0100 to ASM0108 and
Ambiguous project name rows, and the target framework rows, come from 0.2.0. The other
ASM00xx codes, and the Windows and macOS rows, come from 0.3.0 and its lld-link, ld64.lld
and llvm-mc.
First, get the real message. A failed assembler run is reported as ASM0007, naming the
source, right after the assembler's own line (…/a.asm:5: error: …). -v:q hides that line.
Other failed steps surface as:
<sdk>/targets/AsmFoundation.Build.targets(<line>,5): error MSB3073: The command ""…/lld.exe" -flavor link …" exited with code 1.
with the tool's own message just above it.
Add
<AsmFlags>-Xvc</AsmFlags>(best inDirectory.Build.props). NASM's messages then become MSBuild errors and warnings with file and line:a.asm(5): error : instruction expected, found 'movx eax'.llderrors are already recognized:lld : error : ….The command in
MSB3073tells you which step failed:The command runs Step lld -flavor gnu,linkordarwinwith-o/-out:the outputlinking for Linux, Windows or macOS llvm-ar rcsDarchiving a static library lld -flavor link -lib -def:writing an import library (kernel32, the UCRT) nasmorllvm-mconlibc-stub,nonshared,winstdioorcrt1building the C library stand-ins or the startup code
Restore and SDK resolution
| Message | Cause | Fix |
|---|---|---|
MSB4236: The SDK 'AsmFoundation.Sdk' specified could not be found |
no feed has that version, or global.json lacks msbuild-sdks |
add {"msbuild-sdks": {"AsmFoundation.Sdk": "0.3.0"}}; add the feed to nuget.config (folder feeds work) |
ASM0003: TargetFramework 'netstandard2.0' is not an AsmSdk target framework |
a TargetFramework other than freestanding or libc, such as 0.1.0's hidden netstandard2.0 |
freestanding or libc, or TargetFrameworks=freestanding;libc |
ASM0100 to ASM0107: … was removed in AsmFoundation.Sdk 0.2.0, then ASM0108 |
a 0.1.0 setting (AsmLibraryName, AsmRuntime, AsmDefineConstants, AsmDefine, AsmDebugInfo, AsmEntryPoint, AsmLinkFlags, AsmOutputKind) |
the replacement each error names; the changelog has the whole table |
Ambiguous project name 'x' (restore) |
two projects of one restore graph share an AssemblyName, for example a static and a shared build of the same library (libgrpcasm.a, libgrpcasm.so). PackageId defaults to AssemblyName, as in .NET, and NuGet names projects by it. 0.1.0's AsmLibraryName did not touch it, so this appears when migrating. |
give each project its own <PackageId>; the file names still follow AssemblyName |
NU1201: Project X is not compatible with netstandard1.0 (.NETStandard,Version=v1.0) |
a freestanding project references a libc-only project: freestanding code cannot link C library code |
make the reference freestanding (or TargetFrameworks=freestanding;libc), or make this project libc |
NU1202: Package X is not compatible with netstandard1.0 |
the same with a libc-only package |
the same, in the package's project |
ASM0006: There is no bundled toolchain for osx-x64 build machines (or linux-musl-x64) |
LLVM publishes no release binaries for Intel Macs, and its Linux binaries need glibc | <AsmToolchain>System</AsmToolchain> with Homebrew's or Alpine's nasm, llvm and lld, or AsmHostRid set to a toolchain that runs there; see The toolchain |
NU1101: Unable to find package AsmFoundation.Toolchain.<rid> |
the feed holding it is not mapped, or a toolchain version before the build machine had one (0.1.0 had no win-arm64 or linux-arm64) |
check the package source mapping; AsmToolchainVersion 0.2.0 or later |
NU1101: Unable to find package <your package> while the .nupkg is in a folder feed |
package source mapping, possibly from a parent nuget.config, routes the id elsewhere |
map the id's pattern to that feed; start the mapping with <clear /> |
ASM0001: The bundled toolchain was not found in '…' |
built with --no-restore on a clean cache, cleaned caches, or a different NUGET_PACKAGES at build time |
dotnet restore, then build; keep NUGET_PACKAGES the same |
ASM0002: AsmToolchain must be 'Bundled' or 'System' |
typo | fix the value |
MSB4025 … ProjectType '' not found on dotnet build x.slnx |
an .asmproj entry without a type |
<Project Path="…asmproj" Type="13B669BE-BB05-4DDF-9536-439F39A36129" /> |
… has an unknown project type and cannot be added to the solution file from dotnet sln add |
the .NET CLI does not know the .asmproj extension |
add the entry by hand (.slnx: one line with the type GUID), or use new_asmproj.py --sln |
a classic .sln build reports 0 errors but never builds the asm project |
the .sln lists the project but has no ProjectConfigurationPlatforms lines for it |
add {guid}.Debug\|Any CPU.ActiveCfg / .Build.0 lines (and Release), or move to .slnx |
| a changed SDK has no effect while you develop the SDK itself | MSBuild nodes cached the old files | build with -nodeReuse:false, and use a fresh NUGET_PACKAGES |
Runtime identifiers
See Platforms and runtime identifiers for how a project chooses its RIDs.
| Message | Cause | Fix |
|---|---|---|
ASM0010: This project names no runtime identifier to build |
no RuntimeIdentifiers in the project, no referencing project asking for one, no -r |
list the RIDs the code supports: <RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>; or name them on the ProjectReference (RuntimeIdentifiers="…"); or build with -r <rid> |
ASM0011: AsmSdk does not build for linux-x86 |
a RID outside the seven: win-x64, win-arm64, linux-x64, linux-arm64, linux-musl-x64, osx-x64, osx-arm64 |
one of those |
ASM0012: osx-arm64 was asked for (by a referencing project or -r), but this project's RuntimeIdentifiers are … |
a referencing project, a ProjectReference's RuntimeIdentifiers, or -r asks for a RID the project does not list |
add it to the project's list if the code supports it; otherwise build the referencing project for a listed RID |
ASM0040: X.asmproj builds no runtime identifier that linux-arm64 can use. It builds …; linux-arm64 can use … |
a .NET project built for one RID references an asm project none of whose RIDs serves it, by the .NET RID graph | add a serving RID to the asm project (the message lists them), or build the .NET project for another RID |
ASM0041: Cannot read the runtime identifier graph |
the .NET SDK's RuntimeIdentifierGraphPath points to a missing or unreadable file |
repair the .NET SDK installation |
ASM0042: Cannot read … deps.json |
the .deps.json the .NET SDK wrote is missing or malformed when the SDK adds the asm libraries |
rebuild; report it if it persists |
ASM0043: BinariesCopyPath '../out' on the reference to X.asmproj cannot be used: it leaves the output folder |
a BinariesCopyPath that is absolute, has .., a character no OS takes in a file name, or a placeholder other than {rid} |
Auto, Runtimes, AppFolder, RidFolders, or a folder inside the output such as native/{rid} |
ASM0044: X.asmproj's win-x64 build of x.dll and X.asmproj's win-arm64 build of x.dll would both be copied to native/x.dll |
a folder without {rid} in a portable build of several RIDs of one OS; or two libraries with one file name |
add {rid} (the message suggests the folder), or narrow the reference's RuntimeIdentifiers to one RID per OS |
ASM0046: A deploys X.asmproj with BinariesCopyPath 'native', B with 'RidFolders' (warning) |
two .NET libraries of the app chose differently for one asm library | set BinariesCopyPath in the app: on a reference to the asm project, or as the property |
ASM0060: The package X 1.0.0 has no build for osx-arm64 |
an asm project references a package packed for other RIDs | build for a RID the message lists, or use a version packed for yours |
DllNotFoundException in a .NET app on one platform only |
the asm project lists no RID for that platform, or the app was built for another RID | add the RID to the asm project; check runtimes/<rid>/native/ in the output (or the BinariesCopyPath folder) |
DllNotFoundException after moving the libraries with BinariesCopyPath |
something loads them without the host's deps.json and without the generated loader: a NativeAOT program of a VB or F# project, a project with AsmGenerateNativeLibraryLoader=false, or files copied by hand |
check the app's deps.json for the library with its localPath; for NativeAOT keep the default layout (the app folder), or load the library yourself (NativeLibrary.SetDllImportResolver) |
Sources per platform
| Message | Cause | Fix |
|---|---|---|
ASM0023: No source of this project builds linux-arm64 |
an ARM64 RID in a project of .asm files only: NASM assembles x86-64 alone |
add a .s file (GNU syntax) for ARM64, or remove the ARM64 RIDs |
ASM0021: x.arm64.asm is a NASM file (.asm) qualified for 'arm64' |
a .asm file named for ARM64 targets only |
write ARM64 code in a .s file |
ASM0020: For win-x64, x.win.asm and x.win.s apply equally |
two files of one name, equally specific for a RID | keep one, or qualify one more narrowly (x.win-x64.asm) |
ASM0024: Duplicate AsmSource items: x.asm |
a source the default **/*.asm;**/*.s glob includes is listed again |
remove the explicit item, or EnableDefaultAsmItems=false and list every source |
ASM0004: x.s is GNU-syntax assembly for llvm-mc, which AsmFoundation.Toolchain.<rid> 0.1.0 does not include |
a toolchain from before llvm-mc (also for an ARM64 libc build, whose C library stubs are GNU syntax) |
AsmToolchainVersion 0.2.0 or later |
error: unknown section name .note.GNU-stack (macOS) |
the Linux-only note in a source built for macOS | wrap it in %ifdef LINUX … %endif |
error: unrecognised symbol type 'function' (macOS) |
global f:function, which is ELF's |
FUNCTION f from asmsdk.inc, or global f in a macOS file |
error: symbol '..plt' not defined or '..got' not defined (Windows, macOS) |
wrt ..plt and wrt ..got are ELF-only |
call f PLT (empty off Linux); wrt ..gotpcrel on macOS |
error: Mach-O 64-bit format does not support 32-bit absolute addresses |
a memory operand without default rel |
default rel |
error: unrecognised symbol type 'hidden' or 'private_extern' |
each format's visibility keyword in another format's file | HIDDEN_FUNCTION f from asmsdk.inc |
Assembling (NASM)
| Message | Cause | Fix |
|---|---|---|
ASM0007: a.asm: the assembler exited with code 1; its object file was deleted |
any assembler error; the assembler's line comes just before | fix the error it names. The deleted object makes the next build assemble the source again |
warning: implicit DEFAULT ABS is deprecated [-w+implicit-abs-deprecated] (an error with TreatWarningsAsErrors) |
a memory operand in a file without default rel |
add default rel at the top of every source |
warning: 32-bit absolute section-crossing relocation [-w+reloc-abs-dword] |
absolute addressing, usually the same root cause. Also given for dd f wrt ..imagebase (Windows unwind tables), which is right |
default rel |
error: unable to open include file 'b.inc' |
NASM looks in the project folder and the -I folders, never beside the including file |
%include "sub/b.inc", or <AsmIncludeDirectory Include="sub/" />; for a package or reference, check it ships the file under include/ |
error: label, instruction or prefix expected at start of line, found 'rel' |
a symbol named like a keyword or mnemonic (rel, wait, syscall) |
write it as $rel in the definition and in every reference |
error: DEBUG is not defined (from your own %error) |
DisableImplicitConfigurationDefines=true, or a Release build (it defines RELEASE) |
remove the property; test %ifdef DEBUG only for Debug-only code |
a %define written by an MSBuild target came out as Þfine … |
%de in an MSBuild string is an escape for byte 0xDE |
write %25define |
warning: label 'x' alone on a line without a colon might be in error [-w+label-orphan] |
a missing : or a typo |
add the colon; or -w-label-orphan |
warning: dword exceeds bounds [-w+number-overflow] |
the constant is too large for its size | fix the size or the constant |
nasm: warning: unknown warning name: reloc-rel-dword (System toolchain) |
NASM 2.x does not know NASM 3's warning names | harmless; or install NASM 3 |
panic: intra-segment OUT_REL4ADR |
call f wrt ..plt (or call f PLT) to a function in the same section of the same file |
a plain call f: the PLT is for other libraries |
Linking
| Message | Cause | Fix |
|---|---|---|
relocation R_X86_64_PC32 cannot be used against symbol 'f'; recompile with -fPIC (Linux) |
a .so calls a function of another library directly |
call f PLT (wrt ..plt). Within the library, a plain call links, thanks to -Bsymbolic |
relocation R_X86_64_PC32 cannot be used against symbol 'stdout' (Linux) |
a .so reads another library's data directly |
mov rax, [rel stdout wrt ..got] then mov rax, [rax] |
relocation R_X86_64_32S cannot be used against local symbol; recompile with -fPIC (Linux) |
absolute 32-bit addressing (no default rel) in a .so or PIE |
default rel |
relocation R_X86_64_64 cannot be used against local symbol; recompile with -fPIC (Linux) |
mov rax, label, or dq label in a read-only section, in a .so or PIE |
lea rax, [label]; offset tables in .rodata, or dq in .data / a write section |
ASM0080: x.dll needs 1 load-time fixup(s) of a 32-bit absolute address (.text+0x4) (Windows) |
a memory operand without default rel, or dd label: lld-link links it, but a 64-bit image loads above 4 GB, where the address is wrong. The image is deleted |
default rel; dq label in data tables. NASM's 32-bit absolute section-crossing relocation warning names the line |
ASM0081: libx.dylib needs 1 load-time fixup(s) in a read-only segment (rebase at 0x29A in __TEXT) (macOS) |
an absolute address in code or in .rodata (mov rax, label, dq label, a .quad in __text): a text relocation, which Apple's linker refuses. The image is deleted |
lea rax, [rel label]; ADDRESS in GNU syntax; pointer tables in .data |
ASM0082: Cannot check the fixups of … |
the linked image could not be read, or is not the format its OS uses | rebuild; report it if it persists |
ASM0015: A freestanding executable cannot be built for osx-arm64 |
macOS supports no static executables: dyld and libSystem start every program | <TargetFramework>libc</TargetFramework> for a macOS program, or build a library |
ASM0005: AsmToolchain=System links win-x64 with the command in AsmLinkerCommand, and its default, ld, is GNU ld |
the System toolchain's GNU ld links ELF only |
<AsmLinkerCommand>lld-link</AsmLinkerCommand> (Windows) or ld64.lld (macOS) |
ASM0005: AsmToolchain=System links linux-arm64 with the command in AsmLinkerCommand, and its default, ld, is this machine's GNU ld, which links x64 ELF files only |
a distribution's GNU ld links its own machine's ELF only (without the check, GNU ld said file in wrong format) |
<AsmLinkerCommand>ld.lld</AsmLinkerCommand>, which links every architecture, or a cross ld such as aarch64-linux-gnu-ld |
ASM0030: … extern "C++" block or a pattern on Windows |
an ExportsFile the Windows and macOS linkers cannot take as names |
list the exported names directly; Windows takes exact names only |
attempted static link of dynamic object <path>/libx.so (Linux) |
a freestanding Exe was given a .so (a referenced Library, or a package with AsmPackageLinkKind=Shared) |
produce a static library: StaticLibrary or AsmProduceStaticLibrary=true |
undefined symbol: strsignal in a libc program or a Windows or macOS library |
the C library list does not have the function | <AsmLibcSymbol Include="strsignal" />; on Windows the name must be a ucrtbase.dll export |
undefined symbol: x in an Exe, or in a .so linked with -z defs |
a misspelled extern, a missing source or reference, or a symbol that is hidden in another library |
fix the name; add the reference; export the symbol |
duplicate symbol: helper (defined twice at helpers.asm:5) |
an .asm file is %included and also assembled as a source |
rename it .inc, or <AsmSource Remove="helpers.asm" /> |
cannot open <project>/obj/Debug/<tfm>/asm/obj/x.o: no such file or directory (0.1.0, 0.2.0) |
a ProjectReference to an OutputType=Objects project passed object paths relative to the wrong folder |
fixed in 0.3.0, which passes absolute paths |
Builds that pass but behave wrongly
| Symptom | Cause | Fix |
|---|---|---|
editing a shared .inc outside the project does not rebuild |
only AsmInclude items and package or reference folders are dependencies |
add <AsmInclude Include="../common/include/**/*.inc" /> |
| a packaged library's consumers can't find its include file | the producer had no include/ folder, so nothing was packed |
move public files to include/, or declare AsmPublicInclude items |
DEBUG code is missing in Debug builds |
DisableImplicitConfigurationDefines=true |
remove it, or add DEBUG to DefineConstants yourself |
| a shared library exports a dependency's functions | a linked static library's globals (Linux, macOS) or FUNCTION directives (Windows) are exported again |
HIDDEN_FUNCTION or LOCAL_FUNCTION in the dependency; an ExportsFile (Linux, macOS); <LinkerArg Include="--exclude-libs ALL" /> on Linux |
a Windows program has an export table, or a stray <name>.lib |
before 0.3.0, FUNCTION main exported main |
0.3.0 defines ASMSDK_EXECUTABLE, and programs export nothing without an ExportsFile |
RUNPATH is empty although -rpath $ORIGIN is set |
Linux and macOS build machines run the link command through /bin/sh |
per-OS quoting; see Runtimes and linking |
| outputs differ between two machines | NASM embeds each source's absolute path | the same checkout path, or -s in Release |
a typo in an extern in a .so links fine and fails only at load time with undefined symbol |
Linux shared libraries may have undefined symbols | <LinkerArg Include="-z defs" /> |
Running
| Symptom | Cause | Fix |
|---|---|---|
Exec format error |
a build for another CPU or OS: a Linux build on another OS, or an x64 build on Linux ARM64 | run the build of the machine's own RID; Linux builds from Windows run in WSL or docker run … mcr.microsoft.com/dotnet/runtime:10.0 |
Bad CPU type in executable (macOS) |
an osx-x64 program on Apple silicon without Rosetta 2 |
softwareupdate --install-rosetta, or the osx-arm64 build |
Permission denied running an executable in a container |
files built on Windows have no execute bit | chmod +x first |
version 'GLIBC_2.34' not found, or libpthread/libdl symbols missing |
a libc program on a system with glibc older than 2.34 |
a newer distribution (Ubuntu 22.04+, Debian 12+, RHEL 9+), or freestanding |
not found for /lib64/ld-linux-x86-64.so.2 on Alpine |
a glibc build (linux-x64) on musl |
the linux-musl-x64 build, or freestanding |
a crash (SIGSEGV, or 0xC0000005 on Windows) inside printf or another C library function |
the stack not 16-byte aligned at the call (movaps faults); al not set for a System V variadic call; no shadow space on Windows |
sub rsp, SHADOW_SPACE + 8 (or a push) before calling; xor eax, eax before variadic calls on Linux and macOS |
| a crash after returning from your function into C# or Python | a callee-saved register was clobbered: rbx, rbp, r12–r15, and on Windows also rdi, rsi, xmm6–xmm15 |
list them in FUNCTION, which saves those this OS expects back |
wrong results only for negative int arguments |
the code read the 64-bit register for a 32-bit int |
movsxd rax, ARG1d |
Programs: run, publish, deliver and pack
Note
Not released yet: these come from the main branch (see Programs). With
AsmFoundation.Sdk 0.3.0, dotnet run of a program says "The current OutputType is
'Library'" and dotnet publish fails with MSB3030.
| Message | Cause | Fix |
|---|---|---|
ASM0090: X builds a shared library (OutputType Library), and dotnet run starts programs |
dotnet run of a library, static library or object files project |
run a program; a library runs inside the program that loads it |
ASM0091: This machine (win-x64) cannot run any build of X (osx-arm64): … |
no build of the program runs here, natively, emulated, through WSL or in Docker; the message lists what it tried | build a RID this machine runs (dotnet run -r <rid> with the RID in RuntimeIdentifiers), install WSL with a distribution, or start Docker |
ASM0092: X has no built program to run |
dotnet run --no-build before any build |
build first |
ASM0093: AsmRunIn 'x' is not a way to run a program |
a typo | Auto, Host, Wsl or Docker |
exec format error from dotnet run in Docker |
a build for another CPU on a Linux machine without QEMU in binfmt_misc |
install it (docker run --privileged --rm tonistiigi/binfmt --install all), or run the build of the machine's CPU |
error while loading shared libraries: libcalc.so |
a program run from somewhere other than its build or publish folder, without its library next to it; or a program built by AsmSdk 0.3.0, which set no run path | copy the whole folder; rebuild with the main branch |
ASM0047: calc.dll would be copied to lib/, but a Windows program finds the DLLs it links only in its own folder |
BinariesCopyPath other than AppFolder for a Windows RID |
set the value for the other RIDs only (a condition on $(RuntimeIdentifier)) |
ASM0048 (warning): … links calc.dll.lib, the import library of calc.dll, but the package … does not say where calc.dll is |
a package packed by AsmSdk 0.3.0, whose props do not name the DLL | repack the package with the main branch, or copy the DLL next to the program |
ASM0051: A packed program keeps the libraries and programs it needs next to it, and these are in subfolders |
dotnet pack of a program (or a .NET library that carries one) whose libraries are in a BinariesCopyPath folder: NuGet copies runtimes/ files flat into an app built for one RID |
keep them next to the program (AppFolder, the default) |
ASM0053: PackAsTool makes a program a .NET tool, and X builds a SharedLibrary |
PackAsTool on something that is not a program, or with several target frameworks |
OutputType=Exe, one TargetFramework |
| a .NET app does not find the program it references | it looked only in its own folder, and a portable build keeps the program in runtimes/<rid>/native/ |
search NATIVE_DLL_SEARCH_DIRECTORIES, then the app folder (the code is in Programs) |