Troubleshooting

This guide covers common issues you might encounter when using Devark and how to resolve them.

Common Issues

Package manager not detected

Problem: Devark cannot detect your package manager.

✔ Could not detect package manager.

Cause: Your project doesn’t have a lock file (package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb).Solution:

Initialize your project with a package manager

# For npm
npm install

# For yarn
yarn install

# For pnpm
pnpm install

# For bun
bun install

Re-run Devark

devark add <module-name>

Alternative: If you’re starting fresh, Devark will offer to initialize a project for you. Choose your preferred package manager when prompted.

Entry file not found

Problem: Devark can’t find your entry file (app.js, src/app.ts, etc.).

✖ Entry file "app.js" not found.
Please create the entry file and run again.

Cause: The entry file you specified doesn’t exist in your project.Solution:

Create the entry file

For JavaScript:

touch app.js

For TypeScript:

mkdir -p src
touch src/app.ts

Add basic Express setup

app.js (JavaScript):

import express from 'express';

const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

src/app.ts (TypeScript):

import express, { Application, Request, Response } from 'express';

const app: Application = express();

app.get('/', (req: Request, res: Response) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Re-run Devark

devark add <module-name>

For TypeScript projects, make sure your entry file is inside the src/ directory and uses the .ts extension.

Dependency installation fails

Problem: Dependencies fail to install during module setup.

✖ Failed to install dependencies.

Common Causes:

Network issues - npm registry is unreachable
Outdated package manager - Using an old version
Permission issues - Cannot write to node_modules
Disk space - Not enough space for installation

Solutions:

Check network connection

Test if you can reach npm registry:

npm ping

Update your package manager

# For npm
npm install -g npm@latest

# For yarn
npm install -g yarn@latest

# For pnpm
npm install -g pnpm@latest

# For bun
curl -fsSL https://bun.sh/install | bash

Clear cache

# For npm
npm cache clean --force

# For yarn
yarn cache clean

# For pnpm
pnpm store prune

# For bun
rm -rf ~/.bun/install/cache

Install dependencies manually

Check the error message for which packages failed, then:

npm install <package-name>

Check permissions

If you get permission errors:

# Don't use sudo! Instead, fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Add the export line to your ~/.bashrc or ~/.zshrc.

Module already exists error

Problem: Trying to add a module that’s already been added.

✖ This module appears to be already installed.

Cause: The module’s files (routes, config) already exist in your project.Solution:

Check existing files

# Look for module files
ls config/
ls routes/

Remove module files (if you want to reinstall)

# Example for google-oauth
rm config/googleStrategy.js
rm routes/googleAuthRoutes.js

Only remove files if you haven’t made custom changes. Back up first if unsure.

Clean up app.js imports

Remove module-related imports from your entry file:

// Remove lines like:
import googleAuthRoutes from './routes/googleAuthRoutes.js';
import './config/googleStrategy.js';

Re-run Devark

devark add <module-name>

Permission errors on Linux/Mac

Problem: Getting EACCES or EPERM errors.

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Cause: Trying to install global packages without proper permissions.Solution:

NEVER use sudo with npm

Using sudo can cause permission issues. Instead, configure npm properly.

Change npm's default directory

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Update PATH

Add to ~/.bashrc, ~/.zshrc, or ~/.profile:

export PATH=~/.npm-global/bin:$PATH

Then reload:

source ~/.bashrc  # or ~/.zshrc

Reinstall global packages

npm install -g devark

For pnpm users:

pnpm setup
source ~/.bashrc  # or ~/.zshrc

Git conflicts after adding module

Problem: Git shows conflicts in app.js or other files.Cause: Devark modified files that you had uncommitted changes in.Solution:

Stash your changes before running Devark

git stash
devark add <module-name>
git stash pop

Resolve conflicts manually

If conflicts occur:

# Open the conflicting file
code app.js  # or vim, nano, etc.

# Look for conflict markers:
# <<<<<<< HEAD
# Your changes
# =======
# Devark's changes
# >>>>>>> 

# Keep both sets of changes, removing conflict markers

Test your app

npm start
# or
node app.js

Commit the resolved changes

git add .
git commit -m "feat: add <module-name> and resolve conflicts"

TypeScript compilation errors

Problem: TypeScript errors after adding a module.

error TS2307: Cannot find module 'express' or its corresponding type declarations.

Cause: Type definitions are missing or tsconfig.json is misconfigured.Solution:

Install missing type definitions

npm install -D @types/express @types/node
# or for specific modules
npm install -D @types/passport @types/express-session

Check tsconfig.json

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Rebuild the project

npx tsc

Module not found: Cannot find module './routes/...'

Problem: Node.js can’t find the module files that Devark created.

Error [ERR_MODULE_NOT_FOUND]: Cannot find module './routes/googleAuthRoutes.js'

Cause: File path mismatch or files weren’t created in the expected location.Solution:

Verify files were created

ls routes/
ls config/
# or for TypeScript
ls src/routes/
ls src/config/

Check import paths in app.js

For JavaScript (files in root):

import googleAuthRoutes from './routes/googleAuthRoutes.js';

For TypeScript (files in src/):

import googleAuthRoutes from './routes/googleAuthRoutes.js';
// Note: Still use .js extension, not .ts

Check package.json for type

Ensure you have:

{
  "type": "module"
}

This enables ES modules (import/export syntax).

Try absolute path temporarily

To debug, use absolute path:

import { fileURLToPath } from 'url';
import path from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const routesPath = path.join(__dirname, 'routes', 'googleAuthRoutes.js');
console.log('Looking for routes at:', routesPath);

Environment variables not loading

Problem: OAuth credentials or other env vars aren’t being read.

ClientID: undefined
ClientSecret: undefined

Cause: .env file isn’t being loaded or is in the wrong location.Solution:

Check .env file exists

cat .env

Should show:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
SESSION_SECRET=your-session-secret

Ensure dotenv is loaded early

At the top of your entry file:

import 'dotenv/config';
// All other imports after this

Check .env location

The .env file should be in your project root (same directory as package.json):

project/
├── .env          ← Here
├── package.json
├── app.js
└── ...

Debug env loading

Add debug logging:

import 'dotenv/config';
console.log('Env loaded:', {
  clientId: process.env.GOOGLE_CLIENT_ID,
  hasSecret: !!process.env.GOOGLE_CLIENT_SECRET
});

Check for .env in .gitignore

Ensure .env is in .gitignore (for security):

echo ".env" >> .gitignore

Port already in use

Problem: Can’t start server because port 3000 is already in use.

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

Solution:

Find process using the port

# On Linux/Mac
lsof -i :3000

# On Windows
netstat -ano | findstr :3000

Kill the process

# On Linux/Mac
kill -9 <PID>

# On Windows
taskkill /PID <PID> /F

Or use a different port

Change in your app.js:

const PORT = process.env.PORT || 3001;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

Debug Mode

For advanced debugging, you can enable verbose logging:

# Set NODE_DEBUG environment variable
NODE_DEBUG=devark devark add google-oauth

# Or with more detail
DEBUG=* devark add google-oauth

Still Having Issues?

If your issue isn’t covered here, please report it on GitHub Issues with:

Devark version (devark --version)
Node.js version (node --version)
Package manager and version
Full error message
Steps to reproduce

Reporting Bugs

Found a bug? Help us fix it!

Search existing issues

Check if the bug has already been reported: https://github.com/huzfm/Devark/issues

Create a new issue

If not found, create a new issue with:Title: Brief descriptionDescription:

What you were trying to do
What happened
What you expected to happen

Environment:

- OS: [e.g., Ubuntu 22.04, macOS 13, Windows 11]
- Node.js version: [e.g., 18.16.0]
- Package manager: [e.g., npm 9.5.0]
- Devark version: [e.g., 1.1.1]

Steps to reproduce:

Run devark add google-oauth
Select JavaScript
…

Error message:

Paste full error here

Include relevant files

If possible, include:

Your package.json
Your app.js/app.ts (with sensitive data removed)
Screenshots of the error

Getting Help

Need help beyond troubleshooting?

GitHub Issues

Report bugs and request features

GitHub Discussions

Ask questions and share ideas

Quick Fixes Summary

Issue	Quick Fix
Package manager not detected	Run `npm install` to create package-lock.json
Entry file not found	Create app.js or src/app.ts
Permission errors	Configure npm prefix: `npm config set prefix '~/.npm-global'`
Module not found	Check `"type": "module"` in package.json
Env vars not loading	Add `import 'dotenv/config'` at top of entry file
Port in use	Use different port or kill process on port 3000
TypeScript errors	Install missing @types: `npm i -D @types/express @types/node`

Always backup your project before troubleshooting, especially when manually editing files or removing modules.

Commands

Advanced

Troubleshooting

Common Issues

Debug Mode

Still Having Issues?

Reporting Bugs

Getting Help

GitHub Issues

GitHub Discussions

Quick Fixes Summary

Next Steps

Module Structure

Contributing

Build docs developers (and LLMs) love

Commands

Advanced

​Common Issues

​Debug Mode

Still Having Issues?

​Reporting Bugs

​Getting Help

GitHub Issues

GitHub Discussions

​Quick Fixes Summary

​Next Steps

Module Structure

Contributing

Build docs developers (and LLMs) love

Common Issues

Debug Mode

Reporting Bugs

Getting Help

Quick Fixes Summary

Next Steps