> For the complete documentation index, see [llms.txt](https://prodocs.webhash.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prodocs.webhash.com/troubleshooting-faq.md). # Troubleshooting & FAQ Something not working as expected? This page walks through the most common issues in WebHash Pro and how to fix them. Each entry is written as a question, followed by the exact steps to resolve it. If you get stuck after trying these steps, you can always start a fresh deployment from **Dashboard → New Deployment**, or reconnect your GitHub account and wallet - those two actions resolve the majority of problems. {% hint style="info" %} Throughout this guide, "dashboard" means the signed-in area at . The left-hand menu links to **Deployments**, **Domains**, **Billing**, **Environment Variables**, and **Settings**. {% endhint %} *** ## Deployments ### My deploy failed - what do I do? When a build fails, the deployment is marked **Failed** and the error is shown on screen. You don't lose anything - you can read the logs, fix the cause, and try again. **1. Read the logs.** * During a deployment, the **New Deployment** page (Dashboard → New Deployment) shows a live **Deployment Progress** panel with timestamped logs. A failed build ends with a red **Deployment failed** box that includes the error message and an **Error code**. * For an existing deployment, open **Dashboard → Deployments**, click into the repository, then **View Details**. The details page shows a red **Deployment Error** panel (when there's an error) plus the full **Deployment Logs** at the bottom. ![Failed deployment details error panel](/files/bZP2SMEt41HKZpIjk57F) **2. Match the error code to a fix.** The most common codes are: | Error code | What it means | How to fix it | | ------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | `CLONE_FAILED` | We couldn't download your repository. | Confirm the branch exists and that WebHash Pro still has access to the repo (see "I can't see my repository" below). | | `INSTALL_FAILED` | `npm install` (or your package manager) failed. | Check that the project builds locally and that all dependencies are committed to the repo (e.g. a valid `package.json`/lockfile). | | `BUILD_FAILED` | Your build command exited with an error. | Fix the build error shown in the logs, or correct the **Build Command** (see below). | | `OUTPUT_NOT_FOUND` | The build ran, but we couldn't find the output folder. | Set the correct **Output Directory** (see below). | | `QUOTA_EXCEEDED` | The built site is larger than your remaining storage. | Buy more storage in **Billing**, then deploy again. | | `TIMEOUT` | The build took too long. | Try again; very large projects or slow installs can time out. | | `UPLOAD_FAILED` | The site built but couldn't be uploaded to IPFS. | This is usually temporary - try the deployment again. | **3. Redeploy.** Once you've addressed the cause: * For a **failed** deployment, go to the **Dashboard** home page. Failed deployments in the recent list have a **Redeploy** button - click it to re-run the build with the same repository, branch, and settings. * Or run a fresh deployment from **Dashboard → New Deployment**, adjusting the settings before you click **Deploy to IPFS**. ![Dashboard recent deployments with Redeploy](/files/oysSxFcGLvJ4ac0Tv7CU) #### Common build-setting fixes Most `BUILD_FAILED` and `OUTPUT_NOT_FOUND` errors come down to the wrong **Project Type**, **Build Command**, or **Output Directory** on the New Deployment page. * **Static sites** (plain HTML/CSS/JS): choose **Static**. Leave **Build Command** and **Output Directory** empty - WebHash Pro publishes from the repository root. * **React apps**: choose **React**. WebHash Pro pre-fills **Build Command** = `npm run build` and **Output Directory** = `build`. If your project outputs somewhere else, change the Output Directory to match: * Create React App → `build` * Vite → `dist` * If you use a custom build script, set **Build Command** to exactly the command that produces your static files (for example `npm run build`). {% hint style="warning" %} Only **static sites and client-side React apps** are supported. Server-side rendering and backend code will not run on IPFS - if your app needs a running server, it won't work here. {% endhint %} {% hint style="info" %} **Build commands can't contain shell symbols.** For security, characters like `;`, `&`, `|`, `>`, `` ` ``, and `$` are rejected. Keep your build command to a single, simple command such as `npm run build`. {% endhint %} *** ### Why does my deployment seem stuck at "Building" / "Pending"? Deployments run in the background and the page polls for progress automatically. Large repositories or slow dependency installs can take several minutes. 1. Leave the **Deployment Logs** open - new log lines appear as the build progresses. 2. If nothing changes for a long time, refresh the page; the status is read from the server, so a refresh shows the latest state. 3. A build that runs too long ends automatically with a **TIMEOUT** error. If that happens, fix any slow steps (or reduce project size) and redeploy. *** ### My deployment succeeded but the site is missing files / shows a placeholder page WebHash Pro automatically prepares your build for IPFS. A couple of automatic behaviors are worth knowing about: * **Empty (0-byte) files are removed.** The IPFS node refuses any upload that contains an empty file, so WebHash Pro silently drops zero-byte files (for example a placeholder `.gitkeep` or an empty asset) so the rest of your site can publish. You'll see a log line listing what was removed. If a page looks broken, make sure the file actually has content in your repo. * **Paths are rewritten to be relative.** Links and asset paths that start with `/` are converted to `./` so they resolve correctly from an IPFS gateway. If assets still 404, check that they're produced into your Output Directory by the build. * **A `standalone.html` fallback is created.** If your main `index.html` doesn't load, try opening `standalone.html` on the same gateway URL to confirm the bundle is reachable. *** ## IPFS links ### My IPFS link won't load (or is slow the first time) IPFS content is distributed, so a brand-new deployment can take a short while to become reachable through public gateways while it propagates across the network. 1. Confirm the deployment status is **Success** (Dashboard → Deployments → the repository → **View Details**). Only successful deployments have a working gateway URL. 2. Copy the **Gateway URL** from the deployment details (use the copy icon next to it) and open it in a new tab. Use the exact URL WebHash Pro gives you. 3. If it doesn't load on the first try, wait a minute or two and refresh - first-time propagation can be slow. 4. Try the **CID** directly on another public IPFS gateway if your current gateway is having trouble. The **CID** is shown on the deployment details page and can be copied with the copy icon. {% hint style="info" %} Each deployment produces a **new CID** (content identifier). The old CID keeps working - IPFS content is immutable - but it points at the *old* version of your site. To show the latest version on a fixed link, connect an ENS domain (below) and update it to the newest CID. {% endhint %} ![Deployment details IPFS information](/files/nlFae4CQ1gGO8FDZWwuL) *** ## Storage & payments ### I paid but my storage wasn't added If your transaction confirmed on-chain but your storage quota didn't increase, you can recover it yourself from the **Billing** page - no support ticket needed. 1. Go to **Dashboard → Billing**. 2. Scroll to **Payment history**. Find the payment whose status is **not** `confirmed` (it may show `quoted`, `submitted`, or `expired`). 3. Click **Refresh** first - the status may already have updated. 4. If it's still not credited, use the button on that row: * **Check & claim** - appears when WebHash Pro already has your transaction hash on record. It re-checks the payment on-chain and credits the storage. * **Add tx & claim** - appears when no transaction hash is on record. You'll be prompted to paste the transaction hash (the `0x…` value from your wallet or block explorer), then it verifies and credits. 5. When it succeeds you'll see "Payment confirmed - storage credited," and your **Storage usage** meter will update. **If the claim doesn't work, check these:** * **Right wallet.** A payment is tied to the wallet that created the quote. Connect the **same wallet** you paid from. Paying from a different address than the one shown when you bought storage will not credit. * **Right network.** The payment must be on the network you selected when buying (Ethereum Mainnet, Base, Arbitrum, or Optimism). Verifying a transaction from a different network will fail. * **Valid transaction hash.** A transaction hash is a 66-character value starting with `0x`. Copy it exactly from your wallet's activity or from the block explorer. * **"Payment seen on-chain - still confirming."** Your transaction is found but needs more confirmations. Wait a moment and click **Check & claim** again. * **"This transaction has already been used."** That transaction hash was already credited to another payment - each transaction can only fund one purchase. {% hint style="warning" %} If you see **"Quote expired"** while buying, your payment is still safe. WebHash Pro honors a real on-chain payment even after the quote expires - just use **Check & claim** in Payment history to credit it. {% endhint %} *** ### My payment is "rejected" or "failed to send" These messages come from your wallet, not from WebHash Pro: * **"Transaction rejected."** You declined the transaction in your wallet. Click **Buy** again and approve the prompt. * **"Transaction failed to send."** The transaction couldn't be submitted - usually not enough of the token to cover the amount plus network gas fees. Top up your wallet and try again. * **"Please switch your wallet to the selected network."** Approve the network-switch prompt your wallet shows, or switch manually, then retry. *** ### "Storage full" - I can't deploy When a deployment is blocked because you're out of space, you'll see a **Storage full** banner on the New Deployment page (and the deploy is stopped before building). 1. Go to **Dashboard → Billing**. 2. Choose an amount (1, 5, 10, or a custom number of GB), pick a network and token, and click **Buy**. 3. Approve the payment in your wallet and wait for verification. 4. Return to **New Deployment** and deploy again. {% hint style="info" %} The first **20 MB** of storage is free. Beyond that, storage is **$5 per GB**, payable in ETH, USDC, or USDT on Ethereum Mainnet, Base, Arbitrum, or Optimism. {% endhint %} *** ## ENS domains ### My ENS domain still shows the old version of my site Your ENS domain points at a specific **CID**. Every time you deploy, WebHash Pro produces a **new** CID - so after a fresh deployment your domain keeps showing the previous version until you point it at the latest one. To update it: 1. Deploy the new version and wait for it to reach **Success**. Note the new deployment. 2. Open that deployment (Dashboard → Deployments → the repository → **View Details**, or use **Connect Domain** from the repository's deployment list). 3. Click **Connect ENS Domain**. 4. **Connect the wallet that owns the domain** and make sure it's on **Ethereum Mainnet**. 5. Select your domain and click **Connect Domain**. Your wallet will prompt you to sign a transaction that updates the ENS **contenthash** to the new CID. 6. Approve the transaction and wait for it to confirm on-chain. After the transaction confirms, the domain resolves to the new version. Browsers and gateways may cache the old content for a little while - try a hard refresh or a private window. {% hint style="info" %} ENS updates are **self-custodial**: WebHash Pro never holds your keys. Your wallet signs the contenthash change directly, so the update only takes effect once *you* approve and the transaction confirms. {% endhint %} *** ### My ENS domains don't appear in the list 1. Make sure your wallet is **connected** (use the connect button on the **Domains** page). 2. Switch your wallet to **Ethereum Mainnet** - ENS domains are only read from Mainnet. If you're on another network you'll see a "Wrong Network" warning. 3. Confirm you're connected with the **wallet that actually owns the domains**. 4. Click **Refresh Domains**. Network/RPC hiccups can cause a temporary empty list; refreshing usually fixes it. 5. If you've never added a domain, open the [ENS App](https://app.ens.domains) to confirm you own one, then return and refresh. *** ### "You are not the owner of this domain" When you try to connect a domain, the contenthash update is signed by your wallet. If the connected wallet isn't the on-chain owner (or manager) of that ENS name, the transaction is rejected. * Connect the wallet that **owns or manages** the ENS name. * Verify ownership in the [ENS App](https://app.ens.domains). * If you recently transferred the name, wait for that transfer to confirm before connecting. *** ## GitHub & repositories ### I can't see my repository in the list WebHash Pro only sees the repositories you granted it access to when you signed in. If a repo is missing, you likely limited access to specific repositories. 1. On **Dashboard → New Deployment**, use the **search box** first - the list may just be long. 2. Click **Add Repository Access** (top right). This opens GitHub so you can grant WebHash Pro access to more repositories. After approving, you're returned to the dashboard and the new repos appear. 3. For a private repo owned by someone else, use **Add Repo** to enter it as `owner/repo`. If you don't have access, WebHash Pro shows a **Repository Access Required** dialog with two options: prepare an email to the repo owner, or update your GitHub permissions. ![New Deployment repository selection page](/files/hgO4htdlUtDJb1jIuMjX) {% hint style="info" %} After granting more access on GitHub, your **previously selected repositories stay accessible** - you're only adding to the list, not replacing it. {% endhint %} *** ### "Repository not found or not accessible" / "Reconnect GitHub to redeploy" These mean WebHash Pro's GitHub access has lapsed or never included that repo. 1. Go to **Dashboard → New Deployment** and click **Add Repository Access** to re-authorize WebHash Pro on GitHub, selecting the repository you need. 2. Confirm the **branch** you're deploying actually exists in the repository. 3. For private repos, confirm you (the signed-in GitHub user) have access to that repo on GitHub itself. 4. Try the deployment again. *** ### Auto-deploy on push isn't triggering Auto-deploy uses a GitHub webhook to redeploy automatically when you push. 1. On the repository's deployment page (Dashboard → Deployments → the repository), make sure the **Auto-deploy on push** toggle is **on**. 2. Check the **branch** shown next to the toggle - only pushes to *that* branch trigger a deploy. 3. **You need admin access to the repository** to enable auto-deploy. If you see "You need admin access to this repository," ask the repo owner or enable it on a repo you own. 4. If you see a yellow note that auto-deploy "only works once this app is deployed to a public URL," that means GitHub can't reach the current address - auto-deploy will start working once WebHash Pro is reachable at its public URL. ![Auto-deploy on push enabled on a repository](/files/JJQ05A6bASGVfQzVA5Jf) {% hint style="info" %} Auto-deploy reuses the same build settings as your previous deployments for that repository. If those settings were wrong, fix them with a manual deployment from **New Deployment** first. {% endhint %} *** ## Signing in ### I'm having trouble signing in WebHash Pro signs you in entirely through **GitHub OAuth** - there's no separate WebHash password. 1. On [pro.webhash.com](https://pro.webhash.com), click **Sign in with GitHub** and complete GitHub's authorization screen. 2. If you land on an error page, the **error code** is shown at the bottom. Common ones: * **Access denied** - you didn't grant the requested permissions on GitHub. Try again and click **Authorize**. * **Sign-in failed** - the GitHub sign-in couldn't complete. Click **Back to sign in** and retry. * **Account already in use** - your email is linked to a different sign-in method; use the original method. * **Server configuration error** / **Temporary problem** - a transient server-side issue. Wait a moment and try again. 3. Still stuck? Clear your browser cookies for `pro.webhash.com` (or use a private window) and sign in again. ![Auth error page with error code](/files/HdAyi0pnRQB5bkB74vPE) *** ### I get signed out or asked to sign in repeatedly 1. Make sure cookies are enabled for `pro.webhash.com` - the session is stored in a cookie. 2. Disable browser extensions that block cookies or storage for this site. 3. Sign in again from [pro.webhash.com](https://pro.webhash.com). When deep links send you to a sign-in screen, completing GitHub login returns you to the page you originally requested. *** ## Quick reference | Symptom | Where to go | What to do | | --------------------- | ----------------------------------- | ---------------------------------------------------------------------- | | Deploy failed | Deployment details / New Deployment | Read logs, fix build settings, **Redeploy** | | Site won't load | Deployment details | Confirm **Success**, copy the **Gateway URL**, wait for propagation | | Paid, no storage | Billing → Payment history | **Check & claim** / **Add tx & claim** with the right wallet & network | | Out of space | Billing | **Buy** more storage, then redeploy | | Domain shows old site | Deployment → **Connect ENS Domain** | Update contenthash to the latest CID (wallet signs) | | Repo missing | New Deployment | **Add Repository Access** or **Add Repo** | | Can't sign in | pro.webhash.com / /auth/error | Re-authorize on GitHub; clear cookies; retry | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://prodocs.webhash.com/troubleshooting-faq.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.