Troubleshooting

General

// Quick triage - print the human-readable reason on every Login.
std::string key = promptUserForLicense();
if (!Atlas::License::Login(key)) {
    std::cerr << "Login failed: " << Atlas::Data::GetErrorMessage() << "\n";
    return 1;
}

C++ (MSVC)

LNK2019: unresolved external symbol "Atlas::Startup"

Atlas Auth.lib isn't linked, or the library search path doesn't include the SDK folder. See Packaging for Windows.

error C2039: 'API_KEY': is not a member of 'Atlas'

You're compiling against an outdated Atlas.h. Replace it with the current version from the SDK.

Application exits during Startup()

Atlas terminated the process after an integrity check failed. Verify three things:

1. Atlas::API_KEY is set correctly.
2. The application still exists in the dashboard.
3. No debugger is attached. Run with Ctrl + F5, not F5. An attached debugger counts as tampering and can queue a ban against the license or HWID.

The diagnostic exit log in %LOCALAPPDATA%\AtlasAuth\logs\ carries the internal reason string (any binding). See Diagnostic Logs for the full on-disk / server-side split.

Login() returns false

Call Atlas::Data::GetErrorMessage(). Common causes (verbatim from the C++ README):

• An executable hash mismatch (after rebuilding).
• An expired or banned license.
• A banned HWID.
• Invalid credentials.

Account::Login() returns NeedsVerification

That's not a failure - it's the verification flow. The server emailed an 8-digit code. Prompt the user for it and call Account::SubmitVerification(code). If the code didn't arrive, configure an email sender for the application, verify email delivery in Dashboard → Logs, then call Account::ResendVerification() (60-second cooldown).

Process exits unexpectedly after authentication

A runtime integrity check failed. Common causes:

• Modified code sections.
• Injected modules.
• Hooked imports.
• Failed server signature verification.
• An extended heartbeat timeout.

See Dashboard → Logs for the reported reason.

JavaScript (Node.js / Electron)

Atlas.dll not found. Set ATLAS_DLL_PATH or place it beside the .exe.

Thrown at require(), before Startup(). The binding looks in ATLAS_DLL_PATH, then process.resourcesPath (Electron), then beside the running exe, then in the SDK folder. For packaged Electron applications, confirm --extra-resource copied the DLL into resources/. See Electron Example.

Application exits during Startup()

Same as C++ above, plus: the main process isn't running under a debugger. --inspect, VS Code JS debugger, or Chrome DevTools inspector will trip the check. Renderer DevTools are fine.

Login() returns false

Call atlas.Data.GetErrorMessage() - same causes as C++.

Packaged Electron application exits immediately

Verify Atlas.dll is bundled into process.resourcesPath, and if executable whitelisting is enabled, confirm the packaged executable matches the application's configured hash.

EBADPLATFORM / "Unsupported platform" from npm install

Expected. The package declares os: win32 and cpu: x64. Atlas supports native Windows x64 applications only. WSL, Docker, macOS, and Linux aren't supported.

Login fails with an invalid-key error although you set a key

atlas.API_KEY = process.env.ATLAS_KEY assigns undefined when the variable is unset, and the binding doesn't report it. Check the value is a non-empty string before Startup().

Python

OSError: [WinError 193] %1 is not a valid Win32 application

You're running a 32-bit Python interpreter. Atlas requires 64-bit Python.

FileNotFoundError: Atlas.dll not found. Run from SDK tree, frozen via PyInstaller, or set ATLAS_DLL_PATH.

Raised at import atlas, before Startup(). Verify Atlas.dll sits beside the atlas/ package or the application, or set ATLAS_DLL_PATH to its absolute path. On atlas-auth 1.0.3 and earlier, the wheel puts Atlas.dll at sys.prefix while the binding looked beside site-packages: update, or set os.environ["ATLAS_DLL_PATH"] = os.path.join(sys.prefix, "Atlas.dll") before import atlas.

Application exits during Startup()

Same as C++/JS: integrity check failed. atlas.API_KEY set correctly? Application exists in the dashboard? No debugger: pdb, VS Code Python debugger, PyCharm debugger.

Login() returns False

Call atlas.Data.GetErrorMessage() - same causes as C++.

Packaged application exits immediately

Verify Atlas.dll is bundled with the executable, and if executable whitelisting is enabled, confirm the packaged executable matches the application's configured hash.

Still stuck?

Bug reports should include: OS version, language + version, the failing SDK call, and the dashboard Logs entry for the event. Also attach the newest diagnostic exit log from %LOCALAPPDATA%\AtlasAuth\logs\.

• Discord - fastest response.
• Email - [email protected].