Troubleshooting

This guide covers solutions to common problems you might encounter with MolnOS. If you don’t find your issue here, reach out at [email protected] or join MolnOS’s GitHub Discussions.

Installation & Upgrade Issues

npm installation issues

Problem: Installing via npm fails or shows errors

Solution:

1. Ensure Node.js 24+ is installed:

   node --version

2. Check npm is working:

   npm --version

3. For global installation permission errors, use one of these approaches:

   # Option 1: Use a Node version manager (recommended)
   # Install nvm, volta, or similar to avoid permission issues
   
   # Option 2: Configure npm to use a different directory
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc  # or ~/.zshrc
   source ~/.bashrc  # or ~/.zshrc
   
   # Then install globally
   npm install -g molnos

4. For local installation, ensure you’re in a directory with a package.json or create one:

   npm init -y
   npm install molnos

5. Clear npm cache if installation is corrupted:

   npm cache clean --force
   npm install -g molnos

Command not found: molnos

Problem: After installing, running molnos gives “command not found”

Solution:

For npm global installation:

1. Check if npm’s global bin directory is in your PATH:

   npm config get prefix

2. Add npm’s global bin directory to your PATH:

   # For Zsh (macOS default)
   echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   
   # For Bash (Linux default)
   echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

For npm local installation:

Use npx molnos instead of just molnos.

For CLI installer:

Add ~/.local/bin to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Make it permanent by adding this line to your shell profile:

# For Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# For Bash (Linux default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Then restart your terminal or run source ~/.zshrc (or ~/.bashrc).

Node.js version error

Problem: Node.js version 24 or later is required

Solution:

1. Check your current version:

   node --version

2. Install Node.js 24 or later from nodejs.org

3. Verify the installation:

   node --version

Note: If you have multiple Node versions installed (via nvm, Volta, etc.), ensure version 24+ is active.

Installation fails during download

Problem: Installation script fails to download MolnOS

Solution:

1. Check your internet connection

2. Verify you can access https://releases.molnos.cloud

3. Check if you have curl or wget installed:

   curl --version
   wget --version

4. Try the manual installation from releases.molnos.cloud

Permission denied errors during installation

Problem: Permission denied when installing or running MolnOS

Solution:

1. Ensure you have write permissions to ~/.local/bin and ~/.molnos:

   mkdir -p ~/.local/bin ~/.molnos
   chmod 755 ~/.local/bin ~/.molnos

2. Don’t use sudo with the installer—it should install to your user directory

3. If running MolnOS, ensure write permissions in your working directory for database files

MolnOS won’t start after upgrade

Problem: MolnOS fails to start after upgrading, or shows version mismatch errors

Solution:

1. Check current versions:

   # CLI version
   molnos --version
   
   # Core version
   cat ~/.molnos/VERSION

2. Ensure both components are upgraded:

   # Upgrade both CLI and Core
   molnos upgrade
   
   # Or upgrade specific components
   molnos upgrade cli    # CLI only
   molnos upgrade core   # Core only

3. Clear shell hash cache if version command shows old version:

   hash -r
   # Or restart your terminal

4. If upgrade fails, use the standalone upgrade script:

   curl -sSL https://releases.molnos.cloud/upgrade.sh | bash

Upgrade fails or cannot download

Problem: molnos upgrade fails to download or install

Solution:

1. Check internet connectivity:

   curl -sSL https://api.molnos.cloud/prod/version/cli

2. Ensure curl or wget is installed:

   # Test curl
   curl --version
   
   # Install if missing (macOS)
   brew install curl
   
   # Install if missing (Ubuntu/Debian)
   sudo apt-get install curl

3. Check permissions on installation directory:

   chmod 755 ~/.local/bin
   chmod +x ~/.local/bin/molnos

4. Try manual upgrade:

   # Download latest CLI
   curl -sSL -o ~/.local/bin/molnos https://releases.molnos.cloud/molnos-cli.mjs
   chmod +x ~/.local/bin/molnos
   
   # Then install Core
   molnos install

Shell completions not working

Problem: Tab completion doesn’t work for molnos commands

Solution:

For Zsh (macOS default):

1. Ensure completions are installed:

   ls -la ~/.zsh/completions/_molnos

2. Add to your ~/.zshrc if not present:

   fpath=(~/.zsh/completions $fpath)
   autoload -Uz compinit && compinit

3. Restart your shell or reload config:

   source ~/.zshrc

4. Test completions:

   molnos auth <TAB>
   molnos functions <TAB>

For Bash:

Shell completions are only automatically installed for Zsh. For Bash, you’ll need to install them manually or use the CLI without completions.

Configuration Issues

Configuration file not found

Problem: Indication that the configuration file is not being picked up, though it should have been.

Solution:

1. Run molnos init to create a template configuration file
2. Ensure you’re running molnos start from the directory containing your config file
3. Check the file name is exactly molnos.config.json (case-sensitive)

See also “CLI not picking up local configuration”.

Missing required configuration values

Problem: MolnOS won’t start, showing errors like Missing email.host value

Solution: Ensure authentication is configured. You have two options:

Option 1: Email-based authentication (requires SMTP):

{
  "email": {
    "host": "smtp.yourprovider.com",
    "user": "[email protected]",
    "password": "your-smtp-password"
  },
  "molnos": {
    "dataPath": "data",
    "initialUser": {
      "userName": "User Name",
      "email": "[email protected]"
    }
  }
}

Option 2: OAuth authentication (no SMTP required):

{
  "oauth": {
    "presets": {
      "google": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "redirectUri": "https://your-domain.com/auth/oauth/google/callback"
      }
    }
  },
  "molnos": {
    "dataPath": "data",
    "initialUser": {
      "userName": "User Name",
      "email": "[email protected]"
    }
  }
}

See the Configuration Guide for complete details.

CLI not picking up local configuration

Problem: CLI seems to ignore your molnos.config.json file

Solution:

As of version 1.0.0, the MolnOS CLI should use the config file in the installation direction, i.e. ~/.molnos/.

If you want to use MolnOS configurations from any other directory, you will currently have to pass configuration in some other manner, such as with environment variables instead (see Configuration Guide).

Invalid JSON syntax

Problem: Unexpected token or JSON parsing errors

Solution:

1. Validate your JSON using a tool like jsonlint.com
2. Common issues:
   • Trailing commas after the last item in an array or object
   • Missing quotes around keys or string values
   • Unescaped quotes inside strings
   • Comments (JSON doesn’t support comments)

Example of invalid JSON:

{
  "email": {
    "host": "smtp.example.com", // ❌ No comments allowed
    "port": 465,  // ❌ Trailing comma before closing brace
  }
}

Authentication & Email Issues

Not receiving sign-in emails

Problem: Magic link emails never arrive

Solution:

1. Check spam/junk folder - sign-in emails may be filtered

2. Verify email configuration:

   # Check your config has correct SMTP details
   cat molnos.config.json | grep -A 6 "email"

3. Test SMTP connectivity:

   • Verify firewall allows outbound connections to your SMTP port

   • Many cloud providers block port 25—use 465 (SSL) or 587 (TLS)

   • Try connecting manually:

     telnet smtp.yourprovider.com 465

4. Check SMTP credentials:

   • For Gmail, use an app password, not your regular password
   • Verify username is correct (often your full email address)
   • Check password has no typos

5. Verify admin email:

   • Ensure INITIAL_USER_EMAIL matches the email you’re trying to sign in with
   • Check for typos or extra whitespace

6. Check MolnOS logs for SMTP errors when you attempt sign-in

Magic link says “Invalid or expired token”

Problem: Clicking the magic link shows an error

Solution:

1. Request a new link - magic links expire after 15 minutes (default)
2. Check the URL is complete - email clients sometimes break long URLs across lines
3. Verify JWT secret hasn’t changed - if you changed auth.jwtSecret after sending the link, tokens become invalid
4. Check system time - ensure your server’s clock is accurate (JWT validation is time-sensitive)

OAuth authentication not working

Problem: OAuth login fails or redirects don’t work

Solution:

1. Verify redirect URI matches exactly:

   • Check your OAuth provider settings
   • URI must match configuration exactly (including protocol and path)
   • Example: https://your-domain.com/auth/oauth/google/callback

2. Check HTTPS in production:

   • OAuth endpoints require HTTPS in production
   • Development (localhost) can use HTTP
   • Set NODE_ENV=development for local testing

3. Verify OAuth credentials:

   # Check your config has OAuth details
   cat molnos.config.json | grep -A 10 "oauth"

4. Check provider-specific settings:

   • Google: Ensure Google+ API is enabled
   • GitHub: Verify app is not suspended
   • Keycloak: Check realm and client settings

5. Check rate limiting:

   • Default: 10 requests per 15 minutes per IP
   • Wait or adjust oauth.rateLimiting in config

6. Inspect browser console for detailed OAuth errors

Cannot access console (CORS errors)

Problem: Browser console shows blocked by CORS policy errors

Solution:

1. Check allowed domains in your API configuration:

   "server": {
     "allowedDomains": [
       "https://your-frontend-domain.com",
       "http://localhost:8000"
     ]
   }

2. Match the exact domain:

   • Include protocol (http:// or https://)
   • Include port if non-standard (:8000, :3000, etc.)
   • No trailing slashes

3. Restart the API after changing CORS configuration

4. For development only, you can temporarily use ["*"] to allow all domains, but never in production

API & Connectivity Issues

API won’t start

Problem: molnos start fails or exits immediately

Solution:

1. Check for port conflicts:

   # See what's using port 3000
   lsof -i :3000

   Kill the conflicting process or change the port in your configuration file.

2. Check configuration is valid - see Configuration Issues

3. Check Node.js version - must be 24 or later

4. Check logs for error messages when starting

5. Verify required files exist:

   ls -la ~/.molnos/molnos_core.mjs

API connection refused or timeout

Problem: Console cannot connect to API

Solution:

1. Verify API is running:

   # Check if API is listening
   curl http://localhost:3000

2. Configure the CLI to use the correct API URL:

   # Check current API URL
   molnos configure url
   
   # Set to local development
   molnos configure url http://localhost:3000
   
   # Or for remote API
   molnos configure url https://your-api.com
   
   # Or use environment variable (highest priority)
   export MOLNOS_API_URL=https://your-api.com

3. Check firewall rules:

   • Allow inbound connections on API port (default 3000)
   • For cloud deployments, check security groups/firewall rules

4. Verify API URL in console:

   • Open index.html
   • Check window.APP_CONFIG.apiBaseUrl matches your API endpoint
   • Include protocol and port: http://localhost:3000

5. Check network connectivity:

   • For remote API, ensure you can reach it: curl https://your-api.com
   • Check DNS resolution: nslookup your-api.com

6. For cloud deployments:

   • Verify the app deployed successfully
   • Check health check endpoint is passing
   • Review deployment logs for errors

Port already in use

Problem: Error: listen EADDRINUSE: address already in use :::3000

Solution:

1. Find what’s using the port:

   # On Linux/macOS
   lsof -i :3000
   
   # On Linux (alternative)
   netstat -tulpn | grep 3000

2. Kill the process:

   kill <PID>

3. Or change the port in your configuration file, then update your console’s apiBaseUrl accordingly.

Console Issues

Console shows blank page

Problem: Loading the console shows nothing

Solution:

1. Check browser console (F12) for errors

2. Verify API endpoint is correct in index.html:

   <script>
     window.APP_CONFIG = { apiBaseUrl: 'http://localhost:3000' };
   </script>

3. Check API is running and accessible:

   curl http://localhost:3000

4. Clear browser cache and reload (Ctrl+Shift+R / Cmd+Shift+R)

5. Try a different browser to rule out browser-specific issues

6. Check static file server is running (if local), for example:

   python3 -m http.server 8000

Console loads but shows errors

Problem: Console displays error messages or broken features

Solution:

1. Check browser console for JavaScript errors

2. Verify API connectivity - most features require API access

3. Check authentication - try signing out and back in

4. Clear localStorage:

   localStorage.clear()

5. Verify console version matches API version - major versions must align

Cloud Deployment Issues

Data not persisting (DigitalOcean)

Problem: Data disappears after redeployment

Solution:

This is expected with the quickstart configuration. DigitalOcean App Platform uses ephemeral storage.

For persistent data:

1. Deploy to a VM or VPS with persistent storage
2. See Installation Deep Dive for production setup

Getting More Help

If you’ve tried the solutions above and still have issues:

Documentation

• Installation Deep Dive - Complete installation guide
• Configuration Guide - All configuration options
• Integration Guide - Setting up webhooks and automation

Community Support

• GitHub Discussions - Ask questions and share knowledge

Direct Support

• Email: Use [email protected] for general questions
• Commercial customers: Priority support included with license, please direct questions to [email protected]

When reporting issues, include:

• MolnOS version (cat ~/.molnos/VERSION for Core; molnos --version for CLI)
• Operating system and version
• Node.js version (node --version)
• Error messages (full text)
• Relevant configuration (sanitized of secrets)
• Steps to reproduce the issue