Skip to content

troubleshooting.md

Latest commit

 

History

History
140 lines (91 loc) · 2.59 KB

troubleshooting.md

File metadata and controls

140 lines (91 loc) · 2.59 KB

Troubleshooting

Common issues and solutions when using weld.

Diagnostics Checklist

When reporting issues, include:

weld --version
python --version
uname -a                    # OS info
cat .weld/config.toml       # Config (redact sensitive data)
weld doctor                 # Dependency status

If using --debug, include .weld/debug.log.

Common Issues

"Weld not initialized"

Symptom: Command fails with "weld not initialized" error.

Solution: Initialize weld in your project:

weld init

Missing Dependencies

Symptom: weld doctor shows missing tools.

Solution: Install the required tools:

# Install GitHub CLI
brew install gh       # macOS
apt install gh        # Ubuntu/Debian

# Authenticate GitHub CLI
gh auth login

# Install Claude CLI
# See: https://claude.ai/code

Not a Git Repository

Symptom: "Not a git repository" error.

Solution: Initialize git first:

git init
weld init

Output Token Limit Exceeded

Symptom: Error like "Claude's response exceeded the output token maximum."

Solution: Increase the token limit in .weld/config.toml:

[claude]
max_output_tokens = 200000  # Increase from default 128000

AI Provider Timeout

Symptom: Command times out waiting for Claude.

Solution: Increase the timeout in .weld/config.toml:

[claude]
timeout = 3600  # Increase to 1 hour

Permission Errors

Symptom: Cannot write to .weld/ directory.

Solution: Check directory permissions:

ls -la .weld/
chmod -R u+w .weld/

Transcript Generation Failed

Symptom: Commit fails with exit code 21.

Solution:

  1. Check that gh CLI is installed and authenticated
  2. Or skip transcript generation:
weld commit --skip-transcript
  1. Or disable transcripts in .weld/config.toml:
[transcripts]
enabled = false

JSON Output Parsing Errors

Symptom: Exit code 23 when parsing Claude response.

Solution: This usually indicates Claude returned unexpected output. Try:

  1. Run with --debug to see the raw response
  2. Retry the command
  3. Check if your specification is too complex

Debug Mode

Enable detailed logging:

weld --debug <command>

Logs are written to .weld/debug.log.

Getting Help

See Also