Common Issues

Installation and Setup

Before getting started, ensure you have Node.js and Git installed, then install the Adapt CLI globally:

npm install -g adapt-cli

'git is not installed' error when installing Adapt

When running adapt commands, you may receive an error indicating that Git is not installed or not found. Check that Git is installed and available in your system path. See git-scm.com for installation instructions.

Node version mismatch

If npm install or grunt fails unexpectedly, check that your Node.js version meets the framework's requirements. The minimum supported version is listed in the engines field of package.json. Use a version manager like nvm to switch versions:

nvm install 18
nvm use 18

'Local grunt not found' error

This usually means node_modules is missing or incomplete. Delete the folder and reinstall:

rm -rf node_modules
npm install

'Cannot GET /' in the browser after running grunt server

You must run grunt build before grunt server. The server has nothing to serve until the course has been built:

grunt build
grunt server

Running your course

Course fails to load when opened directly from the filesystem

Adapt courses must be served over HTTP or HTTPS. Opening index.html directly in a browser via a file:// path will fail due to browser security restrictions, even if all files are present.

Use grunt server to preview locally, or deploy to any web server.

Course is stuck on a loading spinner

If the course builds successfully but stalls on a loading spinner in the browser, check the browser console for errors. A common cause is a JSON syntax error in one of the course content files (e.g. course.json, contentObjects.json). The console will identify the failing file — fix the syntax error and rebuild.

Server does not support JSON mime-type

Some web servers — typically Microsoft IIS or SharePoint — do not serve .json files by default, causing the course to fail on load.

Option 1 — Add the JSON mime-type to your server configuration (preferred).

Option 2 — If you can't change the server config, use the .txt extension instead. Rename all .json files to .txt, then use the --jsonext flag with Grunt commands:

grunt build --jsonext=txt