Skip to main content

Troubleshooting

Common issues and their solutions when working with Oidis Builder.

Project Not Recognized​

Symptom:

Target folder "..." has not been recognized as Oidis Project root

Causes and fixes:

  1. Wrong working directory — Run oidis from the project root (where package.conf.jsonp lives).

    cd /path/to/my-project
    oidis build dev
    # or use --base:
    oidis build dev --base=/path/to/my-project

  2. Missing package.conf.jsonp — The file must exist at the project root. If you only have package.conf.json, rename it to package.conf.jsonp.

  3. Corrupted JSONP file — Syntax error in package.conf.jsonp. Validate it:

    oidis task system-info

    The builder will print the config load error with line information.

Dependencies Not Found After oidis install​

Symptom:

Failed to load target environment. Missing configuration: .../dependencies/io-oidis-commons/package.conf.jsonp

Causes and fixes:

  1. Install failed silently — Run install with debug output:

    oidis install --debug

  2. Git authentication failed — Verify SSH keys or HTTPS credentials are configured for the dependency repositories.

  3. Wrong branch/tag — Check the changeset in package.conf.jsonp:

    "io-oidis-commons": "git+https://gitlab.com/.../io-oidis-commons.git#develop"
    //                                                                   ^^^^^^^^ branch

  4. Local dependency path wrong — If using dir+ in private.conf.jsonp, verify the path exists:

    "io-oidis-commons": "dir+D:/workspace/io-oidis-commons"

  5. Force clean install:

    oidis clean
    oidis install

TypeScript Compilation Errors​

Symptom: TypeScript errors during oidis build dev

Fixes:

  1. Missing generated files — Interface registrations, namespace maps and the ForceCompile.ts generated block are rewritten by every build (typescript-interfaces, typescript-mappings and typescript-reference run before typescript:source), not by oidis install. Only files containing @Extern(, @Resolver( or @Route( are added to ForceCompile.ts automatically; import any other runtime-resolved class manually outside the generated block.

  2. Outdated dependency types — Pull latest dependency changes and run oidis install:

    # In the dependency directory:
    git pull
    # Then in your project:
    oidis install

  3. ES module import issues — Imports must use the .js extension (even for .ts files):

    // Correct:
    import { MyClass } from "./MyClass.js";
    // Wrong:
    import { MyClass } from "./MyClass";

  4. Missing @io-oidis-* path aliases — These are set up in tsconfig.json via path aliases. Run oidis install to regenerate tsconfig.json.

Module Format Does Not Support Top-level Await​

Symptom:

Module format "iife" does not support top-level await. Use the "es" or "system" output formats rather.

This is a Rollup error during the GUI bundle phase.

Cause:

The project depends on a package (e.g., io-oidis-localhost) that contains top-level await in its frontend code. Without the guiLoaderClass configuration, the builder wraps the frontend bundle in IIFE format, which does not support top-level await.

Fix (two steps):

  1. Set guiLoaderClass in package.conf.jsonp:

    "guiLoaderClass": "Io.Oidis.Localhost.Gui.Loader"

    Use the namespace of the GUI Loader class from your dependency. This tells the builder which class to use as the GUI entry point, enabling the correct module wrapping format.

  2. Import the Loader in Gui/ForceCompile.ts:

    // Manual section — above generated-code-start
    import "@io-oidis-localhost/Io/Oidis/Localhost/Gui/Loader.js";

    Without this import, the Loader class is tree-shaken out of the bundle and the frontend cannot initialize.

See also: ForceCompile — GUI Loader Import | Configuration

SASS Compilation Errors​

Symptom:

SASS compile skipped: no *.scss files have been found

This is a warning, not an error — it means the project has no SASS files. Safe to ignore if your project is TypeScript-only.

Symptom: SASS import errors

  1. Missing dependency SCSS — The dependency's SASS files must be installed. Run oidis install.

  2. Wrong import path — SASS imports in Oidis projects use webpack-style aliases. The @project alias resolves to the project source directory. Ensure your import paths match.

Build Fails with Unable to find target folder​

Symptom: After oidis build prod:

Unable to find target folder

This means compilation succeeded but packaging produced no output in build/target/. Causes:

  1. All platforms skipped — Check target.platforms in your config. If building for a different OS (e.g., building Linux on Windows without cross-compile toolchain), the platform is skipped with a warning:

    Release platform "app-linux-gcc" skipped for "target": out of capabilities on current builder instance.

  2. Missing toolchain — For C++ platforms, the relevant toolchain (GCC, Clang, etc.) must be installed in external_modules/. Run oidis install to download toolchains.

C++ Build Errors​

xcvarsall.bat not found (Windows):

vcvarsPath is not configured

Set vcvarsPath in builder config (e.g., via private.conf.jsonp or builder's global config):

"vcvarsPath": "C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Auxiliary/Build/vcvarsall.bat"

ARM cross-compilation fails: Verify the ARM toolchain is installed in external_modules/aarch32 or external_modules/aarch64. Run oidis install which downloads the configured toolchain.

Lint Errors Blocking Build​

Symptom: oidis build prod fails on lint

For development, run without tests:

oidis build dev    # no lint in dev builds by default

To treat lint errors as warnings instead of failures:

// package.conf.jsonp
"lintErrorsAsWarnings": true
warning

Do not use lintErrorsAsWarnings: true in production builds — lint errors indicate real code quality issues.

copyrights-cleanup Pre-commit Hook Fails​

Symptom: Git commit blocked:

ERROR: Copyright year mismatch in file.ts

The copyrights-cleanup hook enforces correct copyright year ranges. Fix the copyright header in the failing file:

// Correct for a file created in 2024 and modified in 2026:
/*! Copyright 2024 - 2026 Oidis */

// New file created in 2026:
/*! Copyright 2026 Oidis */

Run the task manually to see all violations:

oidis task copyrights-cleanup

Service Mode Issues​

Builder service won't start:

  1. Check if a service is already running:

    oidis service stop
    oidis service

  2. Check the PID file: <appdata>/.oidis/builder.pid

  3. Change the service port if there's a conflict:

    oidis service --port=3667

    Or set servicePort in builder config.

Tasks not forwarding to service:

oidis build dev --service

Ensure the service is running first. Use oidis service to start it.

Deploy Fails​

Authentication failure:

Failed to sign in

Check credentials in private.conf.jsonp. The user and pass must match your Oidis Hub account.

Server not configured:

Target deploy failed: unable to find deploy server configuration

Ensure deploy.server.<type>.location is set in package.conf.jsonp for the target type (dev/eap/prod).

Chunk upload timeout: Reduce chunk size for slow connections:

"deploy": {
    "chunkSize": 1048576
}

(1 MB chunks)

Platform-Specific Issues​

Windows​

Path too long errors: Enable long path support:

Settings → Update & Security → For Developers → Enable long paths

Or in Group Policy: Computer Configuration → Administrative Templates → System → Filesystem → Enable Win32 long paths

oidis not found after install: Ensure the builder install directory is in PATH. Re-run the selfinstaller or add the path manually:

%APPDATA%\oidis\builder\cmd

Linux / macOS​

Permission denied on external_modules/:

chmod -R 755 external_modules/

Python PEP 668 error (cannot install packages into system Python): Oidis Builder handles this automatically by using a virtual environment. If issues persist:

oidis task python-install    # reinstall Python virtual environment

Homebrew Python conflicts (macOS): The builder uses external_modules/python (if present) in preference to system Python. Run oidis install to set up the managed Python environment.

Debugging Build Issues​

Enable verbose debug output:

oidis build dev --debug

Print all executed tasks: The builder prints the task execution log at the end of a debug run:

List of all executed tasks: [solution-loader, build-settings:dev, ...]

Print system info:

oidis task system-info

Check what the builder sees as project config:

oidis --info=version      # print target project version
oidis --info=name         # print target project name
oidis --info=dependencies # print dependency list

Build log: The full build log is written to log/build.log in the project directory.

Frequently Asked Questions​

Q: Can I skip specific tests during build? A: Use oidis build dev (no tests by default) or oidis build prod --skip-test to skip tests in any build type.

Q: How do I build for a single platform instead of all? A: Use a custom solution that overrides target.platforms, or use private.conf.jsonp:

"target": {
    "platforms": ["app-win-nodejs"]
}

Q: Why does oidis install run a full cleanup? A: By default oidis install cleans everything to ensure a consistent state. For faster installs during development:

oidis task install:dev    # partial cleanup only

Q: Can I use multiple solutions simultaneously? A: No — only one solution is active per build. Use multiple build invocations with different --solution flags for multi-solution CI pipelines.

See also: CLI Reference | Configuration | Builder Overview