IPFS Companion for Chrome — Troubleshooting Common IssuesIPFS Companion is a browser extension that integrates the InterPlanetary File System (IPFS) with Chrome, making it easier to access and serve content from the decentralized web. Despite its usefulness, users sometimes encounter issues that can prevent the extension from working smoothly. This article walks through common problems, diagnostic steps, and practical fixes to get IPFS Companion running correctly in Chrome.
1. Confirm basics: installation and compatibility
- Chrome version: Ensure you are running a recent Chrome or Chromium-based browser. Older versions may lack required APIs.
- Extension installed: Verify IPFS Companion appears in chrome://extensions and is enabled.
- Multiple IPFS extensions: Disable other IPFS-related extensions (or multiple instances) — they can conflict.
If any of these are out of order, update Chrome and reinstall the extension.
2. IPFS node connection issues
IPFS Companion works with either a local IPFS node (go-ipfs or js-ipfs) or a remote/public gateway. Common connection problems:
Symptoms:
- Extension shows “No IPFS node found” or “Not connected”.
- Local gateways (http://127.0.0.1:8080 / http://127.0.0.1:5001) are unreachable.
- Requests route through the wrong gateway.
Troubleshooting steps:
- Check whether a local IPFS daemon is running:
- For go-ipfs: run ipfs daemon in a terminal.
- For js-ipfs: start the node using your chosen UI or script.
- Confirm API and Gateway addresses:
- By default, go-ipfs uses Gateway 127.0.0.1:8080 and API 127.0.0.1:5001. If you changed config, ensure Companion’s settings match.
- Verify network binding:
- If your node binds to 0.0.0.0 or another interface, ensure Companion is allowed to connect to that address.
- CORS and API access:
- If Companion cannot call the API, add appropriate CORS headers in the IPFS config (Config > API > HTTPHeaders). For go-ipfs, add:
- Access-Control-Allow-Origin: “chrome-extension://
”, “http://localhost:…”, “*” .
- Access-Control-Allow-Origin: “chrome-extension://
- If Companion cannot call the API, add appropriate CORS headers in the IPFS config (Config > API > HTTPHeaders). For go-ipfs, add:
- Check logs in the extension popup and browser console (chrome://extensions → “Inspect views” under IPFS Companion) for detailed errors.
Common fixes:
- Restart the IPFS daemon and Chrome.
- Reconfigure Companion to use a public gateway temporarily (e.g., https://ipfs.io) to isolate local-node issues.
- Update go-ipfs/js-ipfs and the extension to latest versions.
3. CORS and blocked API calls
Cross-Origin Resource Sharing (CORS) often prevents Companion from accessing a local IPFS API.
Symptoms:
- Errors mentioning CORS or “Access-Control-Allow-Origin” in console.
- Companion cannot pin, add, or fetch via the API.
Fixes:
- Modify the IPFS config to include the extension origin in Access-Control-Allow-Origin under API HTTPHeaders.
- Example for go-ipfs (execute in terminal or edit config):
- ipfs config –json API.HTTPHeaders.Access-Control-Allow-Origin ‘[“chrome-extension://
”]’ - ipfs config –json API.HTTPHeaders.Access-Control-Allow-Methods ‘[“PUT”,“POST”,“GET”]’
- ipfs config –json API.HTTPHeaders.Access-Control-Allow-Origin ‘[“chrome-extension://
- Restart the IPFS daemon after changes.
Security note: avoid setting Access-Control-Allow-Origin to “*” in persistent setups, as it relaxes API access broadly.
4. Gateway content not loading or 404s
Symptoms:
- Navigating to ipfs://
or /ipns/ returns 404 or blank pages. - Resources load partially or CSS/JS assets fail.
Causes & fixes:
- Content not pinned or not available on the network:
- Ensure the content is present locally (ipfs add) or pinned on a node that is online.
- DNSLink/IPNS resolution delays:
- DNSLink records may take time to propagate. Verify with dig or an online DNS checker.
- Path translation issues:
- Companion rewrites ipfs:// and ipns:// to gateway URLs. Configure the preferred gateway in Companion settings; try switching between public and local gateways.
- Subresource loading blocked:
- Mixed content or incorrect Content-Type headers from serving nodes can break loading of assets. Check console for MIME type issues.
5. Slow loading or connectivity problems
Symptoms:
- Pages served over IPFS load very slowly or time out.
- Bitswap or DHT-related errors in logs.
Troubleshooting:
- Verify peer connections: ipfs swarm peers should show active peers. If empty, check network restrictions (NAT, firewall).
- Enable DHT/Rendezvous options if behind NAT, or configure port forwarding for libp2p ports.
- Use public bootstrap nodes: ipfs bootstrap add
. - Consider running a local IPFS HTTP Gateway and pinning popular content to reduce retrieval time.
6. Browser-specific features not working (content scripts, protocol handlers)
Symptoms:
- ipfs:// links are not redirected.
- Companion toolbar icon functions differ or context menu items are missing.
Checks:
- Ensure extension has required permissions enabled in chrome://extensions.
- Verify protocol handler registration: Companion registers ipfs/ipns handlers; conflicts with other handlers or missing permissions can prevent it.
- Reinstalling the extension can re-register handlers.
7. Pinning and remote pinning issues
Symptoms:
- Pin requests fail or time out.
- Remote pinning services return authentication/permission errors.
Fixes:
- For local pinning: ensure your node has sufficient disk space and the repo size is within limits.
- For remote pinning: confirm API keys and endpoints in Companion settings; check the remote pinning service status and their API requirements.
- Use ipfs pin ls and ipfs repo stat to inspect pin state and disk usage.
8. Extension crashes or high resource use
Symptoms:
- Chrome tab or extension process consumes high CPU or memory.
- Extension stops responding.
Actions:
- Inspect background page for errors (chrome://extensions → Inspect views).
- Disable other extensions to check for conflicts.
- Update to the latest Companion release; file a bug report with logs if persistent.
- If using js-ipfs in-browser, consider switching to a local daemon (go-ipfs) to offload resource demands.
9. Troubleshooting checklist (quick)
- Confirm Chrome and extension up to date.
- Ensure a local or remote IPFS node is reachable.
- Check API and Gateway addresses match Companion settings.
- Add necessary CORS headers to IPFS API config.
- Inspect console logs via extension inspector for errors.
- Try switching to a public gateway to isolate local-node issues.
- Verify ports and peer connectivity (firewall/NAT).
- Reinstall the extension to reset handlers/permissions.
10. When to seek help / file a bug
Collect the following before asking for help:
- Chrome version and OS.
- IPFS Companion version.
- go-ipfs or js-ipfs version and how it’s started.
- Relevant logs: extension console, IPFS daemon logs, and any error messages.
- Steps to reproduce the issue.
Report bugs to the IPFS Companion repository with the details above; maintainers can request more logs or reproduction steps.
Troubleshooting IPFS Companion usually reduces to checking node connectivity, CORS/API access, gateway selection, and browser permissions. Systematic logging and isolating whether the issue is local-node vs. gateway vs. extension will get you back online quickly.
Leave a Reply