Degoog Docs

Degoog Troubleshooting

The things that actually go wrong, and what to do about each one.

Every search returns nothing

Almost certainly no engines are installed. Degoog ships with none, on purpose.

Go to Settings, Store, install an engine or two, then enable them in Settings, Engines. The results page will tell you this directly with a link to the Store if you have zero engines.

If that doesn't work, and there's no info in the logs, the next likely culprit is DNS, you can use this handy site to check if that's the case: https://isitdns.com

One engine keeps failing

Look at the sidebar. Degoog names the engine and the reason, and gives you a retry link to re-run just that engine.

  • Blocked by the engine or Blocked by an interstitial page: it needs a different transport. This is the common case with Google. See Tips and tricks.
  • CAPTCHA challenge: usually Cloudflare. FlareSolverr or a stealth browser transport.
  • Rate limited: you are querying too fast from one IP. Enable a proxy, search less aggressively, or leave the cache to do its job.
  • Timed out: raise that engine's timeout in Configure, Advanced, or disable it.
  • Could not read the response: the site changed its markup and the engine extension needs updating. Check Settings, Store for an update.

No suggestions under the search box

No autocomplete provider is installed. They are separate from engines and, like engines, none ship by default. Install one from Settings, Store and enable it in Settings, Autocomplete.

If a provider is installed and enabled but nothing appears, check that the provider itself is reachable from your server and that autocomplete rate limiting has not kicked in.

You cannot get into Settings

  • A password prompt you did not expect. If you never set DEGOOG_SETTINGS_PASSWORDS, Degoog generated a one-off password and printed it in the server logs at startup, under a "Temporary settings password" banner. It changes on every restart, so set the environment variable if you want a stable one.
  • Settings returns 404. The path may have been moved with DEGOOG_SETTINGS_PATH. On a public instance the admin page lives at /admin, and it only responds at all if a password is configured. Without one it returns 404 with no hint that it exists, which is intentional.
  • You get a cut-down settings page. That is DEGOOG_PUBLIC_INSTANCE=true. Visitors see appearance, search options, and engine toggles only. Admin lives at the separate path.
  • "Settings authentication is misconfigured." The gate is set to a middleware plugin that is not loaded, for example after uninstalling an SSO plugin. Fix the gate setting or set DEGOOG_SETTINGS_PASSWORDS.

You banned yourself

If you are seeing a 403 page instead of Degoog, or ASCII art of Gandalf on the homepage, the bot trap caught you. That can happen with unusual clients, aggressive prefetching, or a reverse proxy that hides real client IPs from Degoog. See What to do when you see Gandalf for the full walkthrough.

From an unaffected device or network, open Settings, Server, Bot Control and unban your IP from the Blocked IPs list. If it keeps happening, turn off browser verification (CSS HMAC) or the honeypot entirely while you investigate.

Everyone is getting rate limited

Rate limiting is per client IP. Behind a reverse proxy, Degoog defaults to distrusting forwarded headers, which means every request can look like it comes from the proxy, so a single limit is shared by everyone.

Set DEGOOG_DISTRUST_PROXY=0 only when Degoog sits behind a proxy you control and that strips or rewrites X-Forwarded-For on incoming requests. If Degoog is exposed directly to the internet, leave it alone: trusting those headers would let any client claim any IP.

An extension installed but nothing happened

Work down this list:

  1. Is it enabled? Engines, autocomplete providers, and themes need switching on or selecting after install.
  2. Does the card show Needs configuration? Some engines want an API key or a service URL first.
  3. Does it show Server restart required? The banner at the top of Settings, General has a button.
  4. Does it show Requires a newer version of Degoog? Update Degoog itself.

Thumbnails are missing

Result images are fetched by your server through an image proxy, which blocks private and local addresses by default. If your engine points at something on your own network, such as a Jellyfin or Meilisearch instance, its thumbnails will not load until you turn on Allow local network images in Settings, Server and add a regex pattern for that host.

The UI looks broken

  • Switch back to the built-in theme in Settings, Themes. It is always available.
  • Clear or fix Settings, Server, Custom CSS. It loads last, so it overrides everything.
  • Disable recently installed plugins, particularly slot plugins that inject their own markup.
  • Hard-refresh. Degoog registers a service worker, so a stale cached asset can survive a normal reload.

A setting will not stick

  • Theme, search options, and engine selection are stored in your browser. Clearing site data resets them, and they do not follow you to another device unless someone published them as instance defaults.
  • On a public instance, server-side mutations return Unauthorized by design.
  • If a list is too large to render, Degoog says so and asks you to edit the file directly. That is expected behaviour, not a save failure.

Streaming is on but results still arrive all at once

Check whether you have Use POST method for search requests enabled in your search options. The two are incompatible, and POST wins. The setting even carries a tooltip saying so.

Some buffering reverse proxies also swallow server-sent events. If streaming works locally but not through your proxy, that is where to look, and the Compatibility / Low Resource Mode preset exists precisely for this.

Startup and install problems

  • Permission errors on data/. The container runs as 1000:1000 by default. Run sudo chown -R 1000:1000 ./data, or set PUID and PGID to match your host user.
  • Certificate errors on a native install. Install your distribution's ca-certificates package.
  • The Store cannot clone repositories. A native install needs git on the host. Several transports also need curl.
  • Nothing resolves under a sub-path. Set DEGOOG_BASE_URL to the path you serve from, for example /degoog.

Reading the logs

When the answer is not in the UI, it is in the logs. Set LOG_LEVEL=debug for the full picture, including per-plugin execution times. Where to read the output for each deployment style is covered in Viewing server logs.

Cross-page search fetches the other pages over HTTP, which browsers block from file:// URLs. Serve the docs properly (npm run serve in the docs project) and it works.

Still stuck

The Discord community is active and friendly, and GitHub issues is the right place for genuine bugs. Please have a look through these docs first; a fair number of issues turn out to be "no engines installed".