Troubleshooting - TheTeleporter Scripts

Configuration Issues

Missing credentials in .env file

Error:

✗ Missing credentials in .env file
Required: CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN

Cause:

.env file doesn’t exist
.env file is empty
Required variables are missing

Solution:

Create .env file

cd ~/workspace/source/cloud/gdrive-ingest
cp .env.example .env

Edit .env

nano .env

Add your credentials:

CLIENT_ID="your-client-id.apps.googleusercontent.com"
CLIENT_SECRET="GOCSPX-your-secret"
REFRESH_TOKEN="1//04your-refresh-token"

Save and test

./gdrive_ingest.sh --help

See Google Drive API Setup for getting credentials.

Access token invalid or expired

Error:

ERROR: Refresh failed!

Cause:

REFRESH_TOKEN is invalid
CLIENT_ID/CLIENT_SECRET don’t match the token
Token was revoked

Solution:

Regenerate refresh token

Build authorization URL

Replace YOUR_CLIENT_ID:

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/drive&access_type=offline&response_type=code

Get authorization code

Open URL in browser
Sign in and authorize
Copy the code shown

Exchange for refresh token

curl -X POST \
  -d "code=YOUR_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
  -d "grant_type=authorization_code" \
  https://oauth2.googleapis.com/token

Update .env

Copy refresh_token from response and update .env file.

See full guide: Google Drive API Setup

TELEGRAM_API_ID required

Error:

✗ Telegram API credentials required
Set environment variables:
  export TELEGRAM_API_ID='your_api_id'
  export TELEGRAM_API_HASH='your_api_hash'
Get them from: https://my.telegram.org

Cause: Trying to download from Telegram without API credentials. Solution:

Get credentials

Go to https://my.telegram.org
Log in with your phone number
Click “API development tools”
Create application
Copy api_id and api_hash

Add to .env

.env

TELEGRAM_API_ID="12345678"
TELEGRAM_API_HASH="abc123def456..."

Install Telethon

pip3 install telethon

See Telegram Integration for complete setup.

Dependency Issues

curl: command not found

Error:

curl: command not found

Solution:

sudo apt update
sudo apt install curl

jq: command not found

Error:

jq: command not found

Solution:

sudo apt install jq

ffprobe: command not found

Error:

ffprobe: command not found

Impact: Music files won’t be organized by artist/album. Solution:

sudo apt install ffmpeg

Script will still work without ffmpeg, but music organization features will be disabled.

Telethon not installed

Error:

✗ Telethon library required for Telegram downloads
Install: pip install telethon

Solution:

pip3 install telethon

# Or with user flag
pip3 install --user telethon

# Verify installation
python3 -c "import telethon; print(telethon.__version__)"

Download Issues

Download failed

Error:

⬇  Downloading file.mp3...
✗ Download failed

Possible causes:

Invalid URL

Symptoms:

404 Not Found
Connection refused

Solution:

Verify URL is correct
Check if file still exists
Try opening URL in browser first

Network issues

Symptoms:

Connection timeout
DNS resolution failed

Solution:

# Test connectivity
curl -I https://example.com/file.mp3

# Check DNS
nslookup example.com

Authentication required

Symptoms:

401 Unauthorized
403 Forbidden

Solution:

URL requires authentication
Use Telegram integration for Telegram files
Download manually first, then upload local file

Telegram: Message not found

Error:

ERROR: Message not found

Possible causes:

Message doesn’t exist
Message was deleted
You don’t have access to the channel
Link is incorrect

Solution:

Verify link

Open the link in Telegram app to confirm it exists

Check access

For private channels:

Make sure you’re a member
Logged in with same phone number

Try public link format

# If using private link format
https://t.me/c/1234567890/456

# Try public format (if channel is public)
https://t.me/channelname/456

Telegram: No media in message

Error:

ERROR: No media in message

Cause: The Telegram message is text-only (no file attached). Solution:

Verify the message contains a file
Try a different message number
Check in Telegram app first

Telegram: database is locked

Error:

database is locked

Cause: Session file is locked by another process or crashed session. Solution:

# Remove session journal
rm ~/.config/gdrive-ingest/telegram/*.session-journal

# Or fully reset session
rm -rf ~/.config/gdrive-ingest/telegram/

Next run will prompt for phone number and verification code.

Upload Issues

Upload failed with exit code 26

Error:

⬆  Uploading 8.52MB... ✗ Upload failed
Curl exit code: 26

Cause:

File path issue
Special characters in filename
File doesn’t exist

Solution:

Check file exists

ls -la /tmp/*_$$

Run in debug mode

./gdrive_ingest.sh --debug https://example.com/file.mp3

Check the file path shown

Check for special characters

If filename has special characters, try renaming

Quota exceeded

Error:

✗ Upload failed
API Error: Quota exceeded

Cause: Google Drive storage quota is full. Solution:

Check storage

Go to https://drive.google.com/settings/storage

Free up space

Delete old files
Empty trash
Upgrade storage plan

Retry upload

./gdrive_ingest.sh https://example.com/file.mp3

Already exists, skipping

Message:

⊘ Already exists, skipping

Cause: File with same name already exists in destination folder (duplicate detection). This is normal behavior! Options:

To re-upload anyway

Delete the existing file from Google Drive
Upload to a different folder
Rename the file before uploading

To verify it's actually a duplicate

Check the MD5 checksum:

# Local file
md5sum file.mp3

# Compare with script output
🔐 MD5: 6d2300f6a025e07ad87991b31023da6a

If MD5 matches, it’s the same file.

Music Organization Issues

Music files not organized by artist/album

Symptoms: Music files upload to Music/ root instead of Music/Artist/Album/. Possible causes:

ffprobe not installed

Check:

which ffprobe

Solution:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

No metadata in file

Check: Run in debug mode:

./gdrive_ingest.sh --debug https://example.com/song.mp3

Look for:

Metadata: Unknown Artist|Unknown Album|Unknown Title|

Solution:

Add metadata to file using a tag editor
Or manually specify folder: --folder "Music/Artist/Album"

Metadata is corrupted

Check:

ffprobe -v quiet -show_entries format_tags=artist,album,title file.mp3

Solution:

Re-tag the file
Download from a different source

Cover art not extracted

Symptoms: No cover.jpg uploaded with music files. Possible causes:

ffmpeg not installed

Solution:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

No embedded cover art

Check:

ffmpeg -i song.mp3 -an -vcodec copy cover.jpg

If fails, file has no embedded cover art.Solution:

Download/add cover art to file using a tag editor
Manually upload cover.jpg separately

Cover already exists

Check output:

🖼  Cover art... ⊘ Cover art (already exists)

This is normal - cover is extracted once per album.

Metadata has website spam

Before:

Artist: "Don Toliver (HipHopKit.com)"
Album: "Tiramisu | Audiomack.com"

After:

Artist: "Don Toliver"
Album: "Tiramisu"

Cleaning is automatic! The script removes:

HipHopKit.com
Audiomack.com
SoundCloud
Spotify
YouTube
Generic domains [name].(com|net|org)

If spam remains, file a bug report.

Folder Issues

Folder not found, creating fails

Error:

✗ Failed to create folder

Possible causes:

Invalid credentials

Solution: Check .env file has valid CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN.

Folder name contains invalid characters

Solution: Avoid these characters in folder names:

/ (forward slash)
\ (backslash)
< > (angle brackets)

Permission issues

Solution:

Check you have write access to parent folder
Try creating folder manually in Google Drive web UI
Verify OAuth scope includes drive access (not just drive.file)

Interactive mode not working

Symptoms:

Arrow keys print characters instead of navigating
Screen doesn’t update
Cursor visible during selection

Possible causes:

Terminal doesn't support ANSI

Solution: Use a modern terminal:

Linux: gnome-terminal, konsole, xterm
macOS: iTerm2, Terminal.app
Windows: WSL with Windows Terminal

SSH session issues

Solution:

# Set TERM variable
export TERM=xterm-256color

# Or use non-interactive mode
./gdrive_ingest.sh --folder "Music" url.mp3

tmux/screen interference

Solution:

# In tmux/screen, use non-interactive mode
./gdrive_ingest.sh --folder "Music" url.mp3

Temp Files Cleanup

Temp files accumulating

Check:

ls -lah /tmp/ | grep -E "extract_|upload_result_|tg_download_|single_|covers_"

Cause:

Script was killed (kill -9)
Terminal closed during operation
Script interrupted with Ctrl+C during upload

Solution:

Cleanup Script
Manual Cleanup
System Reboot

./cleanup_temp.sh

Removes all orphaned temp files.

# Current process only
rm -rf /tmp/*_$$

# All sessions
rm -rf /tmp/extract_*
rm -rf /tmp/upload_result_*
rm -rf /tmp/tg_download_*
rm -rf /tmp/single_*
rm -rf /tmp/covers_*

sudo reboot

Clears all /tmp/ files (most Linux systems).

No space left on device

Error:

No space left on device

Check disk space:

df -h /tmp

Solution:

Clean temp files

./cleanup_temp.sh

Use different temp location

export TMPDIR="/path/to/larger/disk/tmp"
mkdir -p "$TMPDIR"
./gdrive_ingest.sh url.mp3

Clear system temp

sudo apt clean
sudo journalctl --vacuum-time=3d

Session Issues

Telegram authentication keeps asking for phone

Symptoms: Every run prompts for phone number and code. Cause: Session file not being saved or is corrupted. Solution:

Check session directory

ls -la ~/.config/gdrive-ingest/telegram/

Should contain downloader.session.

Check permissions

chmod 700 ~/.config/gdrive-ingest/telegram/
chmod 600 ~/.config/gdrive-ingest/telegram/*

Reset session

rm -rf ~/.config/gdrive-ingest/telegram/
mkdir -p ~/.config/gdrive-ingest/telegram/
./gdrive_ingest.sh https://t.me/channel/123

Re-authenticate when prompted.

Google token refresh fails

Error:

ERROR: Refresh failed!

Check token cache:

cat ~/.gdrive_token

Solution:

Remove token cache

rm ~/.gdrive_token

Verify .env credentials

cat .env | grep -E "CLIENT_ID|CLIENT_SECRET|REFRESH_TOKEN"

Make sure all three are present and valid.

Test refresh

./gdrive_ingest.sh --help

Should show:

Refreshing access token...
✓ Token cached successfully

Debug Mode

Using debug mode

When troubleshooting any issue, run in debug mode first:

./gdrive_ingest.sh --debug https://example.com/file.mp3

Shows:

Commands that would run (dry-run)
API queries and responses
File paths and metadata
Duplicate check results
Upload operations

No actual:

Downloads
Uploads
API modifications

Example output:

→ Checking duplicate for: 'song.mp3' in folder: 1hU4H0PO_...
→ Query: name='song.mp3' and '1hU4H0PO_...' in parents and trashed=false
→ No duplicate found
→ Would upload song.mp3 from /tmp/song.mp3_12345
Metadata: Don Toliver|Tiramisu|Tiramisu|2025
→ Would upload cover.jpg

Getting Help

Collect diagnostic info

Before asking for help, collect this information:

Script version

head -n 20 gdrive_ingest.sh | grep -E "^# Version|^# gdrive_ingest"

System info

uname -a
bash --version

Dependencies

curl --version
jq --version
ffprobe -version 2>/dev/null || echo "ffprobe not installed"
python3 --version
python3 -c "import telethon; print(telethon.__version__)" 2>/dev/null || echo "telethon not installed"

Debug output

./gdrive_ingest.sh --debug https://example.com/file.mp3 2>&1 | tee debug.log

Error message

Copy the exact error message and context.

Common debug commands

cat .env | grep -v "^#" | grep -v "^$"

Quick Reference

Issue	Quick Fix
Missing credentials	`cp .env.example .env && nano .env`
Token expired	`rm ~/.gdrive_token`
Telegram auth fails	`rm -rf ~/.config/gdrive-ingest/telegram/`
Temp files remain	`./cleanup_temp.sh`
No space left	`df -h /tmp && ./cleanup_temp.sh`
Upload fails	`./gdrive_ingest.sh --debug url.mp3`
Music not organized	`sudo apt install ffmpeg` (or `brew install ffmpeg`)
Duplicate files	Delete from Drive or upload to different folder

Next Steps

Setup Guide

Complete setup instructions

Google Drive API

Fix credential issues

Telegram Integration

Fix Telegram issues

Usage Examples

See working examples

Get Started

Scripts

GDrive Ingest

Development

​Configuration Issues

​Missing credentials in .env file

​Access token invalid or expired

​TELEGRAM_API_ID required

​Dependency Issues

​curl: command not found

​jq: command not found

​ffprobe: command not found

​Telethon not installed

​Download Issues

​Download failed

​Telegram: Message not found

​Telegram: No media in message

​Telegram: database is locked

​Upload Issues

​Upload failed with exit code 26

​Quota exceeded

​Already exists, skipping

​Music Organization Issues

​Music files not organized by artist/album

​Cover art not extracted

​Metadata has website spam

​Folder Issues

​Folder not found, creating fails

​Interactive mode not working

​Temp Files Cleanup

​Temp files accumulating

​No space left on device

​Session Issues

​Telegram authentication keeps asking for phone

​Google token refresh fails

​Debug Mode

​Using debug mode

​Getting Help

​Collect diagnostic info

​Common debug commands

​Quick Reference

​Next Steps

Setup Guide

Google Drive API

Telegram Integration

Usage Examples

Build docs developers (and LLMs) love

Configuration Issues

Missing credentials in .env file

Access token invalid or expired

TELEGRAM_API_ID required

Dependency Issues

curl: command not found

jq: command not found

ffprobe: command not found

Telethon not installed

Download Issues

Download failed

Telegram: Message not found

Telegram: No media in message

Telegram: database is locked

Upload Issues

Upload failed with exit code 26

Quota exceeded

Already exists, skipping

Music Organization Issues

Music files not organized by artist/album

Cover art not extracted

Metadata has website spam

Folder Issues

Folder not found, creating fails

Interactive mode not working

Temp Files Cleanup

Temp files accumulating

No space left on device

Session Issues

Telegram authentication keeps asking for phone

Google token refresh fails

Debug Mode

Using debug mode

Getting Help

Collect diagnostic info

Common debug commands

Quick Reference

Next Steps