Troubleshooting | Documentation

Common installation and runtime issues, with step-by-step solutions to get you back on track.

Installation Issues

"Repository not found" Error

This error occurs when GitHub can't authenticate or you don't have access to the repository.

Solution 1: Accept GitHub Invitation

Check your email or visit: https://github.com/boltaai/devconsole-package/invitations

Solution 2: Verify Authentication

bash

# Check GitHub CLI authentication
gh auth status

# If not authenticated, run:
gh auth login

Solution 3: Use Personal Access Token

bash

# Create token at: https://github.com/settings/tokens
# Then configure:
git config --global credential.helper store
echo "https://YOUR_TOKEN@github.com" >> ~/.git-credentials

"Authentication failed" During Install

Your GitHub credentials may have expired or are incorrect.

For GitHub CLI:

bash

gh auth login

For Personal Token:

bash

# Verify token hasn't expired
# Regenerate if needed at: https://github.com/settings/tokens
# Ensure it has 'repo' scope

Clear Cached Credentials (macOS):

bash

git credential-osxkeychain erase
host=github.com
protocol=https
# Press Enter twice

Slow Installation / Recursive Installs

The package may be installing its own dependencies recursively, causing slow installs.

Solution: Use Post-Install Cleanup

json

// Add to your package.json
{
  "scripts": {
    "postinstall": "node node_modules/devconsole-package/scripts/postinstall-cleanup.js"
  }
}

This removes unnecessary files (source code, node_modules, etc.) from the installed package, keeping only the dist folder needed for runtime.

Next.js Build Errors

ERR_INVALID_ARG_VALUE with null bytes

Next.js is trying to create file paths using the git dependency URL, which contains invalid characters.

Solution: Update next.config.ts

typescript

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  transpilePackages: ['devconsole-package'],
  
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.alias = {
        ...config.resolve.alias,
        'devconsole-package': require.resolve('devconsole-package'),
      };
    }
    
    config.output = {
      ...config.output,
      chunkFilename: (pathData) => {
        const chunkName = pathData.chunk?.name || 'chunk';
        return `static/chunks/${chunkName.replace(/[@+]/g, '_')}-[id].js`;
      },
    };
    
    return config;
  },
};

export default nextConfig;

Package Installs But Can't Import

The package may not have built correctly or there's a cache issue.

bash

# 1. Clear Next.js cache
rm -rf .next

# 2. Clear pnpm cache
pnpm store prune

# 3. Reinstall
rm -rf node_modules
pnpm install

# 4. Verify package built correctly
ls node_modules/devconsole-package/dist/

CSS Loading Issues

CSS Not Loading / Styles Not Appearing

CSS auto-loading may have failed, especially with git-installed packages.

Solution 1: Manual CSS Loading (Recommended)

tsx

import { DebugToolkit, DebugProvider, GodModeProvider, loadStyles } from 'devconsole-package';

// Load CSS manually
loadStyles();

function App() {
  return (
    
      
        
        
      
    
  );
}

Solution 2: Direct CSS Import

tsx

import 'devconsole-package/dist/styles/debug-toolkit.css';
import { DebugToolkit, DebugProvider, GodModeProvider } from 'devconsole-package';

Note: This may not work with git-installed packages due to path resolution issues.

Solution 3: Verify CSS is Loaded

javascript

// Check in browser console
document.querySelector('link[data-devconsole-styles]')
// Or
document.querySelector('style[data-devconsole-styles]')

CI/CD Deployment Issues

"Repository not found" on Vercel

Your deployment platform can't access the private repository.

1. Ensure you've accepted the GitHub invitation

2. Verify GITHUB_TOKEN is set

Vercel: Settings → Environment Variables → Add GITHUB_TOKEN

3. Token must have 'repo' scope enabled

4. Use the helper script in your build command

json

// vercel.json
{
  "buildCommand": "./node_modules/devconsole-package/scripts/setup-git-auth.sh && npm run build"
}

Build Failures on Deployment

Common causes and solutions for deployment build failures.

Check that GITHUB_TOKEN is set in environment variables
Verify the token hasn't expired
Ensure pnpm-workspace.yaml is committed to your repository
Check build logs for specific error messages

Configuration Issues

.devconsole.json Not Being Picked Up

The toolkit may fail to find your custom configuration file if it's not placed in the correct location, if there's a CORS issue, or if Next.js middleware is blocking the request (common with dotfiles).

Solution 1: Check File Location

The file MUST be named exactly .devconsole.json and must be in your project's public/ folder.

Solution 2: Use API Route Fallback (Recommended for Next.js)

If you're getting 400 errors when accessing /.devconsole.json, create an API route to serve the config. The toolkit automatically falls back to this route if the direct file fetch fails.

typescript

// src/app/api/devconsole-config/route.ts
import { NextResponse } from 'next/server';
import fs from 'fs';
import path from 'path';

export async function GET() {
  try {
    const configPath = path.join(process.cwd(), 'public', '.devconsole.json');
    const configContent = fs.readFileSync(configPath, 'utf-8');
    const config = JSON.parse(configContent);
    
    return NextResponse.json(config, {
      headers: {
        'Content-Type': 'application/json',
        'Cache-Control': 'public, max-age=3600',
      },
    });
  } catch (error) {
    console.error('[DevConsole] Failed to load config:', error);
    return NextResponse.json(
      { error: 'Config not found' },
      { status: 404 }
    );
  }
}

The toolkit will automatically try /api/devconsole-config if the direct file fetch fails. No additional configuration needed!

Solution 3: Verify Access

Try navigating to http://localhost:3000/.devconsole.json or http://localhost:3000/api/devconsole-config in your browser. If both fail, check your middleware configuration.

Solution 4: Check Console Logs

Open the browser devtools. The toolkit will log [DevConsole] Loaded config from API route. when the fallback succeeds, or [DevConsole] No .devconsole.json file found if both attempts fail.

Still Having Issues?

If you're still experiencing problems, try these general troubleshooting steps:

bash

# 1. Clear all caches
rm -rf .next node_modules pnpm-lock.yaml

# 2. Clear pnpm store
pnpm store prune

# 3. Reinstall everything
pnpm install

# 4. Verify package installation
ls node_modules/devconsole-package/dist/

# 5. Check for TypeScript errors
pnpm tsc --noEmit

If issues persist, check the TROUBLESHOOTING.md file in the package repository for more detailed solutions.