Troubleshooting IPFS Companion for Chrome: Common Issues & FixesIPFS Companion for Chrome is a browser extension that integrates the InterPlanetary File System (IPFS) with your browser, making it easier to access content-addressed resources, manage gateways, and interact with local or remote IPFS nodes. While the extension simplifies IPFS usage, users sometimes encounter problems caused by configuration, network settings, or interactions with other extensions. This article covers common issues and step-by-step fixes, plus tips to avoid problems in the future.
Quick checklist before troubleshooting
- Ensure Chrome is updated to the latest stable version.
- Update IPFS Companion to the latest release from the Chrome Web Store.
- Confirm you have a working IPFS node (local or remote) if you rely on one. IPFS Companion can operate in gateway-only mode but some features require a node.
- Disable other privacy/security extensions temporarily (ad blockers, HTTPS Everywhere, script blockers) to see if they interfere.
- Restart the browser after changing settings or updating extensions.
1) Extension won’t install or enable
Symptoms:
- The extension fails to install from the Chrome Web Store.
- Installation succeeds but the toggle is grayed out or the extension won’t enable.
Fixes:
- Check Chrome’s extension policy settings (chrome://extensions/) for administrator restrictions — on managed devices an admin may block installs.
- Ensure you have sufficient disk space and that Chrome’s profile isn’t corrupted. Try creating a new Chrome profile and install there.
- If installation fails with a store error, retry after clearing Chrome cache or sign out/in to your Google account.
- Re-download from the official Chrome Web Store page; avoid side-loading untrusted builds.
2) IPFS Companion icon missing or not responding
Symptoms:
- Extension icon doesn’t appear in the toolbar.
- Clicking the icon produces no response.
Fixes:
- Check chrome://extensions/ to confirm the extension is enabled.
- Use the puzzle-piece menu in Chrome and pin the IPFS Companion extension to show its icon.
- If the icon is present but non-responsive, disable and re-enable the extension, then restart Chrome.
- If still unresponsive, inspect the extension background page (chrome://extensions/ → Details → Service worker) for errors, and report them with logs.
3) Can’t connect to local IPFS node
Symptoms:
- Companion reports “No local node found” or can’t connect to the daemon.
- Gateway requests time out or return ⁄503.
Fixes:
- Verify the IPFS daemon is running: open a terminal and run:
ipfs daemon
or check your IPFS Desktop app status.
- Confirm API and Gateway addresses in your node config (usually ~/.ipfs/config). Default API: /ip4/127.0.0.1/tcp/5001; Gateway: /ip4/127.0.0.1/tcp/8080.
- In IPFS Companion settings, ensure “Use local IPFS node” is enabled and the API/Gateway addresses match your node config.
- If using a custom API port or a non-local node, specify the correct multiaddr in Companion.
- Check for firewall or security software blocking localhost ports. Allow connections on 127.0.0.1:5001 and 127.0.0.1:8080.
- If your node uses a Unix socket or different bind address, Companion may not support that—switch to TCP or run a compatible daemon.
4) IPFS links open in regular HTTP gateway instead of local node
Symptoms:
- Clicking ipfs:// or ipns:// links opens content via a public gateway rather than your local node.
Fixes:
- In IPFS Companion settings, check “Intercept IPFS links” and choose “Redirect to local gateway” or similar option.
- Ensure your local gateway is running and its address is configured correctly in Companion.
- Some sites embed ipfs:// links in ways Companion can’t intercept; try copying the ipfs:// URL into the browser address bar.
- If another extension rewrites URLs (privacy or redirect extensions), disable it for testing.
5) Mixed content / HTTPS problems
Symptoms:
- Browser blocks IPFS content when visiting HTTPS pages (mixed content warnings).
- IPFS resources served over HTTP get blocked.
Fixes:
- Use a local gateway that supports HTTPS and configure Companion to use it; set up a local reverse proxy (e.g., Caddy or nginx) to provide TLS for your gateway.
- Use Companion’s “Use public gateway over HTTPS” option if local HTTPS isn’t available (trade-off: uses remote gateway).
- For testing, you can temporarily allow insecure content for specific pages in Chrome settings, but do not keep this enabled permanently.
6) Slow content retrieval or missing peers
Symptoms:
- Fetching IPFS content is very slow or never completes.
- Few or no peers are visible.
Fixes:
- Ensure your node has proper network connectivity: check swarm addresses (ipfs id, ipfs swarm peers).
- Open necessary ports for libp2p (default 4001) or enable NAT traversal. If behind CGNAT, enable relay/AutoNAT features or use a relay/circuit provider.
- Add bootstrap nodes or use public gateways to seed content. Example: ipfs bootstrap add
. - Increase bitswap/connection timeouts only if you understand performance implications.
- Use IPFS Cluster or pinning services for important content to improve availability.
7) CORS or API permission errors
Symptoms:
- Companion shows CORS errors when calling local API from web pages.
- API requests are blocked.
Fixes:
- IPFS daemon includes CORS settings in the config file. Run:
ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["http://localhost:8080","https://your.site"]' ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["GET","POST","PUT"]'
Restart the daemon after changes.
- Ensure Companion isn’t trying to access the API from an origin not included in Access-Control-Allow-Origin. Add the needed origins.
- For development only, set Access-Control-Allow-Origin to [“*”] temporarily.
8) IPNS publishing or resolution fails
Symptoms:
- ipns name publish fails or ipns:// addresses don’t resolve.
Fixes:
- Ensure your node has an unlocked key for publishing; check ipfs key list and ipfs name publish output.
- If using IPNS over DHT, ensure the DHT is reachable—open ports and bootstrap nodes are necessary.
- For faster updates, consider using DNSLink (DNS TXT records) as an alternative to IPNS.
- If resolution is inconsistent, wait for propagation and ensure peers cache updates.
9) Conflicts with other extensions (adblockers, privacy tools)
Symptoms:
- Content blocked, requests stripped, or Companion features not working.
Fixes:
- Temporarily disable extensions like uBlock Origin, Privacy Badger, or script blockers and retest.
- Add site/extension exceptions where needed.
- Use Chrome’s extension inspection to see network requests and which extension is modifying them.
10) Error messages and logs — how to gather and report
What to collect:
- Chrome version and IPFS Companion version (from chrome://extensions/).
- Whether you’re using a local node or gateway-only mode and the node version (ipfs version).
- Exact error messages, screenshots, and steps to reproduce.
- Console logs from the extension service worker (chrome://extensions/ → Details → Service worker → Inspect) and daemon logs (~/.ipfs logs or terminal output).
How to report:
- Include collected info when filing an issue on the IPFS Companion GitHub repository. Provide config snippets (redact private keys), CORS settings, and any network/firewall details.
Preventive tips and best practices
- Keep Chrome and IPFS Companion updated.
- Run a local IPFS node if you want full control and privacy; otherwise use trusted public gateways over HTTPS.
- Use DNSLink for stable content addressing when publishing websites.
- Pin important content via pinning services or IPFS Cluster.
- Regularly back up your IPFS keys and config.
If you want, I can:
- Help diagnose a specific error if you paste the exact message or logs.
- Provide commands to configure CORS, firewall rules, or a TLS reverse proxy for a local gateway.