Troubleshooting

Common issues and solutions for the Pinner CLI. If you can't find your issue here, run pinner doctor to gather diagnostic information.

Quick Fixes

Authentication Issues

# Check authentication status
pinner doctor

If you're not authenticated:

# Interactive login
pinner auth --email your@email.com
 
# Or provide token directly
pinner auth YOUR_API_TOKEN

Your session token has expired. Re-authenticate:

pinner auth --email your@email.com

Connection Issues

1. Check your internet connection
2. Verify the API endpoint is accessible:

ping pinner.xyz

3. Check if you're behind a firewall or proxy
4. Try with --secure=false to use HTTP (not recommended for production):

pinner --secure=false upload myfile.txt

File Issues

1. Verify the file path is correct
2. Check file permissions:

ls -la /path/to/your/file

3. Use absolute paths:

pinner upload /absolute/path/to/file.txt

1. Check file ownership:

ls -la /path/to/file

2. Change permissions if needed:

chmod 644 /path/to/file

Authentication Errors

Not Authenticated

Cause: No authentication token is configured.

# Method 1: Interactive login
pinner auth --email your@email.com
 
# Method 2: Provide token directly
pinner auth YOUR_API_TOKEN
 
# Method 3: Use environment variables
export PINNER_EMAIL="your@email.com"
export PINNER_PASSWORD="yourpassword"
pinner auth

• PINNER_EMAIL - Email address
• PINNER_PASSWORD - Password
• PINNER_OTP - 2FA code (if enabled)
• PINNER_AUTH_TOKEN - API token (alternative to login)

Registration Issues

1. Verify your email format is correct
2. Check password meets requirements (usually 8+ characters)
3. Ensure you're not using an already registered email:

pinner register --email new@email.com

After registration, you must confirm your email:

pinner confirm-email --email your@email.com --token VERIFICATION_TOKEN

Check your email for the verification token. If you didn't receive it:

1. Check spam folder
2. Verify the email address is correct
3. Try registering again

Upload Errors

Upload Failed

Cause: The upload operation could not complete.

1. Check your internet connection
2. Verify file is readable:

cat /path/to/file > /dev/null && echo "File is readable"

3. Try with a smaller file first
4. Check available disk space
5. Increase memory limit for large files:

pinner upload largefile.dat --memory-limit 1024

Upload Interrupted

Cause: Upload was interrupted (Ctrl+C or network issue).

Solution: The CLI supports resume for TUS uploads. Try uploading again:

pinner upload file.dat --wait

Invalid CID

Cause: The content identifier (CID) format is invalid.

1. Verify the CID is correct
2. CIDs should start with Qm, bafy, or similar multiformat prefix
3. Example valid CID: bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq

Pinning Errors

Pin Not Found

Cause: The specified CID is not pinned in your account.

1. List your pins to verify:

pinner list

2. Check if the CID is correct
3. Pin the content if not already pinned:

pinner pin bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq

Pinning Failed

Cause: The pinning operation could not complete.

1. Verify the CID exists on IPFS
2. Check your network connection
3. Try again later
4. Check pin status:

pinner status bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq

Configuration Issues

Configuration Not Found

Cause: No configuration file exists.

Solution: Run setup to create configuration:

pinner setup

Configuration is stored at ~/.config/pinner/config.toml (Linux/macOS) or %APPDATA%\pinner\config.toml (Windows).

Configuration Invalid

Cause: Configuration file contains invalid values.

1. Check configuration:

pinner config get

2. Reset configuration:

pinner setup --reset

3. Edit config manually or delete and re-run setup

Network Errors

Connection Failed

Cause: Cannot connect to the Pinner API.

1. Check internet connection:

curl -I https://pinner.xyz

2. Check firewall/proxy settings
3. Try with verbose output:

pinner --verbose upload file.txt

Network Timeout

Cause: Request timed out.

1. Try again (may be temporary)
2. Use a more stable network connection
3. Increase timeout by retrying the operation

Input Validation Errors

Path Required

Cause: No file path provided for upload.

pinner upload /path/to/file.txt

CID Required

Cause: No CID provided for pin/status operations.

pinner pin bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq

Invalid CID Format

Cause: CID format is not recognized.

1. Verify the CID is correct
2. CIDs are case-sensitive
3. Example valid CID: bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq

No CIDs Provided

Cause: No CIDs specified for batch operation.

Solution: Provide CIDs directly or use a file:

# Direct CIDs
pinner pin bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco
 
# From file (one CID per line)
pinner pin --file cids.txt

Getting Help

Run Diagnostics

Use the doctor command to gather diagnostic information:

pinner doctor

For JSON output (useful for bug reports):

pinner doctor --json

Verbose Output

Enable verbose mode to see detailed logs:

pinner --verbose upload file.txt

Check Configuration

View your current configuration:

pinner config get

Still Need Help?

1. Run pinner doctor to gather diagnostic info
2. Search existing issues
3. Open a new issue with:
   • Error message
   • Steps to reproduce
   • Configuration output (pinner doctor)
   • Operating system and version

Environment Variables Reference

Shell Completion

If shell completion isn't working:

# Setup bash completion
echo 'source <(pinner completion bash)' >> ~/.bashrc
 
# Setup zsh completion
echo 'source <(pinner completion zsh)' >> ~/.zshrc
 
# Setup fish completion
pinner completion fish > ~/.config/fish/completions/pinner.fish