CLI Troubleshooting

Common issues, error messages, and solutions for the LangCTL CLI tool.

Authentication Issues

Invalid API Key

Error: Authentication failed: Invalid API key

echo $LANGCTL_API_KEY | head -c 3
cat ~/.langctlrc

langctl auth logout
langctl auth login

langctl auth keys list

Error: No API key found. Run: langctl auth login

ls -la ~/.langctlrc

langctl auth login

export LANGCTL_API_KEY="lc_your_key_here"

langctl auth whoami

Error: Permission denied: insufficient scopes

langctl auth keys info

Error: langctl: command not found

npm list -g @langctl/cli

npm install -g @langctl/cli

echo $PATH
npm bin -g

export PATH="$(npm bin -g):$PATH"

$(npm bin -g)/langctl --version

Error: EACCES: permission denied

sudo npm install -g @langctl/cli

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
npm install -g @langctl/cli

npx @langctl/cli --version

Error: Cannot find module '@langctl/cli'

npm cache clean --force

npm uninstall -g @langctl/cli
npm install -g @langctl/cli

yarn global add @langctl/cli
pnpm add -g @langctl/cli

Error: ETIMEDOUT: connection timed out

ping api.langctl.com

echo $HTTP_PROXY
echo $HTTPS_PROXY

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

curl -I https://api.langctl.com

Error: SSL certificate problem: unable to get local issuer certificate

brew install ca-certificates

sudo apt-get update && sudo apt-get install ca-certificates

export NODE_TLS_REJECT_UNAUTHORIZED=0

Error: Rate limit exceeded. Try again in X seconds

sleep 60
langctl export mobile-app -l en

langctl auth keys info

Problem: Export file is empty or has no keys

langctl keys list mobile-app --published

langctl export mobile-app -l en --include-drafts

langctl export mobile-app -l en --module auth

langctl projects info mobile-app

Error: Unsupported export format: xyz

langctl export mobile-app -l en -f i18next

Error: ENOENT: no such file or directory

mkdir -p ./locales

langctl export mobile-app -l en -o ./locales/en.json

langctl export mobile-app -l en -o ~/project/locales/en.json

Error: JSON parse error: Unexpected token

cat import.json | jq .

langctl import mobile-app -l en ./import.json

Error: Invalid character encoding

file -I translations.json

iconv -f ISO-8859-1 -t UTF-8 input.json > output.json

langctl import mobile-app -l en output.json

langctl import mobile-app -l en input.json --encoding utf-8

Error: Duplicate key found: home.welcome

cat import.json | jq 'keys | group_by(.) | map(select(length > 1))'

langctl import mobile-app -l en import.json --update

Error: Project not found: mobile-app

langctl projects list

langctl projects info mobile-app

langctl org current

langctl org use correct-org-id

langctl export project-uuid-here -l en

Error: Project limit reached for your plan

langctl org info

langctl projects list
langctl projects delete old-project

langctl org upgrade --plan pro

Error: Translation key already exists: home.welcome

langctl keys update mobile-app home.welcome --value-en "New value"

langctl keys delete mobile-app home.welcome
langctl keys create mobile-app home.welcome --value-en "Welcome"

Error: Translation key limit reached

langctl projects info mobile-app

langctl keys list mobile-app | grep "unused"
langctl keys delete mobile-app unused.key.* --force

langctl org info
langctl org upgrade --plan team

Error: Invalid configuration file

cat ~/.langctlrc | jq .

rm ~/.langctlrc
langctl auth login

vim ~/.langctlrc

Error: EACCES: permission denied, open '/Users/user/.langctlrc'

chmod 600 ~/.langctlrc

ls -la ~/.langctlrc

sudo chown $USER ~/.langctlrc

Error: CLI version X.X.X is not compatible with API version Y.Y.Y

npm update -g @langctl/cli

langctl --version

npm cache clean --force
npm install -g @langctl/cli

Warning: This command is deprecated. Use 'langctl newcommand' instead

langctl old-command

langctl new-command

langctl help new-command

export DEBUG=langctl:*
langctl export mobile-app -l en

langctl export mobile-app -l en --debug

langctl export mobile-app -l en --verbose

langctl export mobile-app -l en --debug 2> debug.log

langctl --help

langctl export --help
langctl keys --help

langctl --version

langctl examples export

langctl doctor

LangCTL Diagnostic Report
=========================

✓ CLI version: 1.0.0
✓ Node.js version: 18.16.0
✓ Operating system: macOS 13.3
✓ Configuration file: Found (~/.langctlrc)
✓ API key: Valid
✓ Network: Connected to api.langctl.com
✓ Authentication: Successful
✓ Organization: Acme Corp (Pro plan)

No issues detected.

langctl doctor > diagnostic-report.txt

If you can’t resolve the issue:

Check documentation: docs.langctl.com
Search issues: github.com/langctl/cli/issues
Email support: [email protected]
Include diagnostic info:

echo "CLI Version:" && langctl --version
echo "Node Version:" && node --version
echo "OS:" && uname -a
echo "Error:" && langctl your-command 2>&1

💡

Tip

When reporting issues, include your CLI version, Node.js version, OS, and the full error message with stack trace.

Common Solutions Summary

Issue	Quick Fix
Command not found	`npm install -g @langctl/cli`
Authentication failed	`langctl auth login`
Network timeout	Check internet/proxy/firewall
Empty export	Add `--include-drafts` flag
Import failed	Validate JSON syntax
Permission denied	Check API key scopes
Project not found	Verify project name with `langctl projects list`
Rate limited	Wait and retry with delays

Next Steps

CLI Installation - Reinstall or update CLI
Authentication - Fix auth issues
FAQ - Common questions
GitHub Issues - Report bugs