Skip to content

Troubleshooting Guide

Common issues and solutions for Kiosque.

Table of Contents

  1. Installation Issues
  2. Configuration Issues
  3. Authentication Issues
  4. Article Extraction Issues
  5. TUI Issues
  6. Network Issues
  7. Platform-Specific Issues

Installation Issues

command not found: kiosque

Problem: After installing, the kiosque command is not available.

Solutions:

  1. Check installation method:
# If installed with pip:
pip show kiosque

# If installed with uv:
uv run kiosque  # Run directly
  1. Verify PATH:
# pip installs to user directory, check it's in PATH:
python -m site --user-base
# Add <output>/bin to your PATH
  1. Use Python module syntax:
python -m kiosque

ModuleNotFoundError: No module named 'kiosque'

Problem: Python can't find the kiosque module.

Solutions:

  1. Verify installation:
pip list | grep kiosque
  1. Check Python version:
python --version  # Must be 3.12+
  1. Reinstall:
pip uninstall kiosque
pip install kiosque

pandoc: command not found

Problem: Pandoc is not installed (required for HTML to Markdown conversion).

Solutions:

macOS:

brew install pandoc

Linux (Ubuntu/Debian):

sudo apt-get install pandoc

Linux (Fedora):

sudo dnf install pandoc

Windows:

choco install pandoc

Or download from: https://pandoc.org/installing.html

Configuration Issues

"Configuration file not found"

Problem: Kiosque can't find the configuration file.

Solutions:

  1. Find config location:
python -c "from kiosque.core.config import configuration_file; print(configuration_file)"
  1. Create configuration directory:
mkdir -p ~/.config/kiosque
  1. Create configuration file:
cat > ~/.config/kiosque/kiosque.conf << 'EOF'
[https://www.example.com/]
username = your_username
password = your_password

[raindrop.io]
token = your_raindrop_token
EOF
  1. Custom location via environment variable:
export XDG_CONFIG_HOME=/custom/path
kiosque

"Invalid configuration format"

Problem: Configuration file has syntax errors.

Solutions:

  1. Check INI format:
# Good ✓
[https://www.lemonde.fr/]
username = user@example.com
password = mypassword

# Bad ✗ (missing section)
username = user@example.com
password = mypassword
  1. Check for typos:
  2. Section names must be URLs with https://
  3. URL must end with /

  4. Key names: username, password, token (lowercase)

  5. Validate with Python:

from kiosque.core.config import config_dict
print(config_dict)  # Should print dict, not error

Authentication Issues

"Login failed" or "403 Forbidden"

Problem: Can't log in to website despite correct credentials.

Solutions:

  1. Verify credentials:
  2. Log in manually via browser to confirm they work
  3. Check for special characters that need escaping

  4. Some sites use email, others use username

  5. Check if login flow changed:

# Enable verbose logging to see login details:
kiosque -v https://website.com/article -

  1. Known broken logins: See tests/test_login.py for list of websites with outdated login flows.

  2. Two-factor authentication:

  3. Kiosque doesn't support 2FA

  4. Some sites allow app-specific passwords - try creating one

  5. IP-based restrictions:

  6. Some sites block VPN/proxy connections
  7. Try disabling VPN temporarily

"Invalid username or password"

Problem: Credentials rejected by website.

Solutions:

  1. Check configuration file syntax:
[https://www.example.com/]
username = user@example.com  # No quotes needed
password = mypassword123      # No quotes needed
  1. Verify credentials work in browser:
  2. Try logging in manually
  3. Check for password reset requirements

  4. Verify subscription is active

  5. Check for special characters:

# If password contains special chars:
password = p@ssw0rd!#123  # Should work as-is

Article Extraction Issues

"Website not supported"

Problem: URL is not recognized by Kiosque.

Solutions:

  1. Check supported websites:
  2. See Supported Sites for complete list

  3. 30+ websites currently supported

  4. URL must match base_url:

# Good ✓
kiosque https://www.lemonde.fr/article/...

# Bad ✗ (missing www subdomain)
kiosque https://lemonde.fr/article/...
  1. Contribute support for new website:
  2. See Contributing Guide
  3. Adding a new site is usually straightforward

"Article content is empty" or "NotImplementedError"

Problem: Kiosque can't extract article text.

Solutions:

  1. Website changed HTML structure:
  2. This is the most common issue
  3. Websites update their design, breaking scrapers

  4. Open an issue on GitHub with:

    • Website name
    • Example article URL
    • Error message or empty output

  5. Article requires JavaScript:

  6. Some sites load content dynamically with JS
  7. Kiosque only handles static HTML

  8. Workaround: Try reading in browser reader mode instead

  9. Paywall blocking content:

  10. Some paywalls hide content in HTML (not just visually)
  11. Verify you're logged in (use -v flag to check)
  12. Some sites may block programmatic access even with credentials

"Unwanted elements in output"

Problem: Ads, navigation, or other junk appears in article text.

Solutions:

  1. File an issue with:
  2. Website name
  3. Example article URL
  4. Description of unwanted elements

  5. Screenshot if helpful

  6. Quick fix (for developers): Edit the website's clean_nodes in kiosque/website/<site>.py: 

    clean_nodes: ClassVar = [
    "figure",
    ("div", {"class": "unwanted-element"}),
]

TUI Issues

"No bookmarks found" in TUI

Problem: TUI launches but shows no bookmarks from Raindrop.io.

Solutions:

  1. Check Raindrop.io token:
# Verify token in config file:
cat ~/.config/kiosque/kiosque.conf | grep token
  1. Verify token is valid:
  2. Visit https://app.raindrop.io/settings/integrations
  3. Check if token is still active

  4. Generate new token if needed

  5. Check for unsorted bookmarks:

  6. TUI only shows Unsorted bookmarks
  7. Move bookmarks to Unsorted collection in Raindrop.io

  8. Or modify code to fetch from different collection

  9. Test API manually:

from kiosque.api.raindrop import Raindrop

raindrop = Raindrop(token="your_token")
items = raindrop.retrieve()
print(f"Found {len(items)} bookmarks")

TUI crashes or freezes

Problem: TUI becomes unresponsive or crashes.

Solutions:

  1. Check terminal size:
  2. TUI requires minimum terminal size

  3. Resize terminal to at least 80x24

  4. Kill and restart:

# If frozen, kill with:
Ctrl+C  # or Ctrl+Z then kill %1

# Restart:
kiosque
  1. Check logs:
# Run with verbose logging:
kiosque -v tui
  1. Update Textual: 
    pip install --upgrade textual

Problem: TUI keys don't respond as expected.

Solutions:

  1. Verify keybindings:
  2. Esc closes modal
  3. q quits (when not in modal)

  4. See README for full keybindings

  5. Terminal compatibility:

  6. Some terminals don't send all keys correctly

  7. Try a different terminal (e.g., iTerm2, Alacritty)

  8. Check for key conflicts:

  9. Some terminals intercept keys (e.g., tmux)
  10. Try running outside tmux/screen

Network Issues

"Connection timeout" or "Network error"

Problem: Requests to websites time out.

Solutions:

  1. Check internet connection:
ping google.com
  1. Retry logic is automatic:
  2. Kiosque retries 3 times with exponential backoff

  3. Wait for all retries to complete (may take 30+ seconds)

  4. Increase timeout (for developers): Edit kiosque/core/client.py:

client = httpx.Client(timeout=60.0)  # Increase from 30.0
  1. Check firewall/proxy:
  2. Some corporate networks block certain sites
  3. Try from different network

"SSL certificate verification failed"

Problem: HTTPS requests fail due to SSL errors.

Solutions:

  1. Update CA certificates:
# macOS:
brew update && brew upgrade openssl

# Ubuntu:
sudo apt-get update && sudo apt-get upgrade ca-certificates
  1. Temporary workaround (not recommended):
export CURL_CA_BUNDLE=""
kiosque https://example.com/article

"Too many requests" or "Rate limited"

Problem: Website blocks requests due to rate limiting.

Solutions:

  1. Wait before retrying:

  2. Most rate limits reset after 15 minutes - 1 hour

  3. Slow down requests:

  4. Don't download many articles rapidly
  5. Add delays between downloads

"403 Forbidden" or "406 Not Acceptable" - Geo-blocking

Problem: Website blocks access from your geographic location.

Known geo-blocked websites:

  • Courrier International - Returns 406 outside France/Europe
  • Les Échos - Returns 403 (Akamai CDN) outside France/Europe

Solutions:

  1. Use SOCKS or HTTP proxy:

Kiosque supports routing traffic through proxies. Configure in ~/.config/kiosque/kiosque.conf:

# Add proxy configuration
[proxy]
url = socks5://localhost:1080

Supported proxy types: - socks4://host:port - SOCKS4 proxy - socks5://host:port - SOCKS5 proxy (recommended) - http://host:port - HTTP proxy - https://host:port - HTTPS proxy

With authentication:

[proxy]
url = socks5://username:password@host:port
  1. Set up SSH tunnel (SOCKS5):

If you have SSH access to a server in the target region:

# Create SOCKS5 proxy on localhost:1080
ssh -D 1080 -N user@server-in-france.com

# In another terminal, configure kiosque to use it:
# Edit ~/.config/kiosque/kiosque.conf and add:
# [proxy]
# url = socks5://localhost:1080

# Then run kiosque normally
kiosque https://www.courrierinternational.com/article/...
  1. Use commercial VPN service:

Many VPN services offer SOCKS5 proxies: - NordVPN: Supports SOCKS5 proxy - ExpressVPN: Via manual configuration - Shadowsocks: Open-source SOCKS5 solution

Configure the proxy URL from your VPN provider in kiosque.conf.

  1. Test proxy connection:
# Test if proxy works (requires curl with SOCKS support):
curl --socks5 localhost:1080 https://www.courrierinternational.com/

# Should return HTML, not 406 error
  1. Verify proxy in logs:

When proxy is configured, you'll see on startup:

INFO:root:Using SOCKS proxy: socks5://localhost:1080

Note: Proxy configuration applies to ALL HTTP requests made by Kiosque. To disable, simply remove or comment out the [proxy] section in kiosque.conf.

  1. Use browser as fallback:
  2. If blocked, open URL with o key in TUI
  3. Website may have bot detection

Platform-Specific Issues

macOS: "Operation not permitted"

Problem: Permission denied errors on macOS.

Solutions:

  1. Grant Terminal full disk access:
  2. System Preferences → Security & Privacy → Privacy

  3. Full Disk Access → Add Terminal

  4. Fix config directory permissions:

chmod 755 ~/.config
chmod 755 ~/.config/kiosque
chmod 644 ~/.config/kiosque/kiosque.conf

Linux: "Permission denied" writing files

Problem: Can't save downloaded articles.

Solutions:

  1. Check file permissions:
ls -la ~/output.md
  1. Specify output location:
kiosque https://example.com/article ~/Downloads/article.md
  1. Fix ownership:
sudo chown $USER:$USER ~/output.md

Still Having Issues?

Before Opening an Issue

  1. Update to latest version:
pip install --upgrade kiosque
  1. Check existing issues:

  2. https://github.com/yourusername/kiosque/issues

  3. Gather debug information:

# Run with verbose logging:
kiosque -v https://website.com/article - 2>&1 | tee debug.log

# Include in issue:
# - Python version: python --version
# - Kiosque version: pip show kiosque
# - OS: uname -a (Linux/Mac) or ver (Windows)
# - Error message or debug.log
# - Steps to reproduce

Open an Issue

Include:

  • Description of the problem
  • Steps to reproduce
  • Expected vs. actual behavior
  • Python version, OS, kiosque version
  • Relevant logs (with -v flag)
  • Example article URL (if applicable)

Get Help

Common Error Messages Reference

Error Message Likely Cause Solution
Website not supported URL not in supported list Check Supported Sites or add support
NotImplementedError: article() Website HTML changed Open issue with example URL
ConnectionError Network issue Check internet, retry
HTTPStatusError: 403 Blocked or login failed Check credentials, verify subscription
HTTPStatusError: 404 Invalid URL Verify URL is correct
HTTPStatusError: 429 Rate limited Wait 15-60 min before retry
ModuleNotFoundError Installation issue Reinstall kiosque
FileNotFoundError: pandoc Pandoc not installed Install pandoc
ValidationError Config file invalid Check INI syntax
AttributeError: 'NoneType' Article element not found Website HTML changed, open issue

Debug Mode

Enable maximum verbosity for troubleshooting:

# CLI:
kiosque -v https://website.com/article -

# Python:
import logging
logging.basicConfig(level=logging.DEBUG)

from kiosque import Website
website = Website.instance("https://website.com/article")
website.save("https://website.com/article", "test.md")

This will show:

  • HTTP requests and responses
  • Login flow details
  • HTML parsing steps
  • Errors with stack traces