Troubleshooting — Fixing Builds, Deploys, CMS, and DNS

How to Use This Chapter

When something breaks, the first instinct is to search for the symptom. This chapter is organized by where the problem occurs, not by what it looks like. If the site builds locally but fails on Netlify, start with the Deploy section. If content renders wrong on the live site, start with the Content section.

Each section lists:

• The symptom — what you see when something is wrong
• The cause — the most likely reason
• The fix — what to do
• How to verify — how to confirm the fix worked

Every problem has a solution. None of them require rebuilding from scratch. Most take under five minutes.

This chapter covers:

1. Local build — dotnet run -- build and dotnet run -- start

2. Git — pushing, authentication, branch issues

3. Netlify deploy — build failures, deploy timeouts, environment

4. Decap CMS — login, publish, media library

5. DNS and HTTPS — custom domain, certificate, propagation

6. Content rendering — YAML, Markdown, empty sections

7. Templates — missing partials, broken layouts

8. How to read logs — where the real error lives

---

Local Build Problems

dotnet is not recognized

Symptom: running dotnet run -- build in the terminal produces:

'dotnet' is not recognized as an internal or external command

or (on macOS/Linux):

dotnet: command not found

Cause: the .NET SDK is not installed, or it is installed but not on your PATH.

Fix:

1. Open a fresh terminal window. Existing terminals do not pick up PATH changes made after they were opened.

2. If the fresh terminal still fails, verify the SDK is installed:

   dotnet --version

   

3. If the command still fails, re-install the SDK from dotnet.microsoft.com/download. Choose the SDK, not the runtime.

4. On macOS/Linux, if installed via the install script, add to your shell config:

   export DOTNET_ROOT=$HOME/.dotnet

   export PATH=$PATH:$HOME/.dotnet:$HOME/.dotnet/tools
   

Then source ~/.bashrc (or ~/.zshrc).

5. On Windows, restart your computer after installing the SDK.

Verify: dotnet --version prints 9.0.x.

MSBUILD : error MSB1009: Project file does not exist

Symptom: running dotnet run -- build fails immediately:

MSBUILD : error MSB1009: Project file does not exist.
Switch: Dax.csproj

Cause: you are not in the dax-pro directory. The command expects Dax.csproj in the current directory.

Fix:

1. Print your current directory:

   pwd

   

or on Windows:

   cd

   

2. Navigate to the project:

   cd ~/Projects/dax-pro

   

3. Verify Dax.csproj exists:

   ls Dax.csproj

   

4. Retry dotnet run -- build.

Verify: the build starts with D.A.X - Dotnet by AXcora.

Build succeeds but site/ is empty

Symptom: dotnet run -- build outputs [DAX] built 0 pages. The site/ folder has no HTML.

Cause: the content/ folder has no .md files, or the files are in the wrong location.

Fix:

1. Check the content folder:

   ls content/

   

There should be index.md, about.md, contact.md, and subfolders posts/, services/.

2. If content/ is empty, the ZIP extraction went wrong. Re-extract the project ZIP into a clean folder.

3. If content/ has files but the build says 0 pages, check the frontmatter of one file. The file must start with --- on line 1.

Verify: the build output now lists page counts like [DAX] built 49 pages.

Build fails with [BUILD ERROR] Object reference not set to an instance of an object

Symptom: the build starts, then crashes with a null reference exception.

Cause: a YAML file or Markdown frontmatter has a structural problem that the simple parser cannot handle. The most common triggers:

• A value with a colon that is not quoted (title: My: Title)
• A value with a # that is not quoted (url: /#pricing)
• Windows line endings (CRLF) in a file that should be LF
• A nested list deeper than two levels
• A partial include pointing to a file that does not exist

Fix:

1. The error does not tell you which file. Bisect by moving files out:

   mkdir _backup

   mv content/posts _backup/
   dotnet run -- build
   

2. If the build now succeeds, the problem is in content/posts/. Move files back one at a time, rebuilding after each until the failure returns. The last file moved is the culprit.

3. If the build still fails, repeat for content/services/, then content/.md, then _data/.yaml.

4. When you find the file, open it. Check:

- Line 1 is --- (no spaces, no BOM)

- Closing --- is followed by a blank line

- Every value with a colon or # is quoted

- Line endings are LF (see below)

- Nested lists are no deeper than two levels

Verify: the build completes without [BUILD ERROR].

Frontmatter renders as body text

Symptom: a page shows raw YAML at the top instead of rendering it as metadata:

---
layout: post.dax
title: My Post

[actual body content]

The --- and title: appear as text on the page.

Cause: the frontmatter delimiters are not being recognized. This happens when:

• Line 1 has a BOM (UTF-8 with BOM encoding)
• The closing --- is not followed by a blank line
• The file has Windows line endings (CRLF) instead of Unix (LF)

Fix:

1. Open the file in VS Code

2. Check the status bar at the bottom right:

- Encoding should say UTF-8, not UTF-8 with BOM

- Line ending should say LF, not CRLF

3. If the encoding is BOM:

- Click UTF-8 with BOM → Save with Encoding → UTF-8

4. If the line ending is CRLF:

- Click CRLF → LF

5. Save the file

6. Confirm the closing --- is followed by a blank line (press Enter once after it)

7. Rebuild

Verify: the page renders with the title in the browser tab, not raw YAML at the top.

Changes to CSS or templates do not appear

Symptom: you edited style.css or a .dax file, but the browser shows the old version.

Cause: either the build has not run, or the browser has cached the old CSS.

Fix:

1. Rebuild:

   dotnet run -- build

   

2. Hard-refresh the browser:

- Windows/Linux: Ctrl + Shift + R

- macOS: Cmd + Shift + R

3. If the change still does not appear, open DevTools (F12), check the Network tab, and confirm the CSS request is hitting the current build (not a cached response).

Verify: the change appears after a hard-refresh.

---

Git Problems

git push asks for a password

Symptom: git push prompts for a username and password. Your GitHub password does not work.

Cause: GitHub removed password authentication for Git operations in 2021. You must use a personal access token instead.

Fix:

1. Generate a token at github.com/settings/tokens. Choose Generate new token (classic). Scopes: repo and workflow.

2. Copy the token (it looks like ghp_...).

3. When git push asks for a password, paste the token instead.

4. The push succeeds.

To avoid the prompt every time: store the token in Git's credential helper, or use SSH keys instead of HTTPS.

Verify: the push completes without a password prompt on future pushes.

git push fails with 403 Forbidden

Symptom: git push fails with an error like:

remote: Permission to user/repo.git denied.
fatal: unable to access 'https://github.com/...': The requested URL returned error: 403

Cause: the token is expired, has insufficient scopes, or you do not have write access to the repository.

Fix:

1. Regenerate the token with repo and workflow scopes

2. Update the stored credential:

   git remote set-url origin https://your-username:[email protected]/your-username/your-repository.git

   

3. Retry git push

Verify: the push succeeds.

git push fails with failed to push some refs

Symptom: the push is rejected:

! [rejected]        main -> main (fetch first)
error: failed to push some refs

Cause: the remote repository has commits you do not have locally. This happens when the repository was modified on GitHub (or by another machine) after your last pull.

Fix:

1. Pull first:

   git pull origin main

   

2. Resolve any merge conflicts if they appear

3. Push again:

   git push

   

If you are certain your local version is correct and want to overwrite the remote (use with caution):

git push --force origin main

Force push can destroy remote work. Only use it if you know the remote has nothing you need.

Verify: the push succeeds.

git commit says "Author identity unknown"

Symptom: committing fails with:

Author identity unknown
* Please tell me who you are.

Cause: user.name and user.email are not configured.

Fix:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Retry the commit.

Verify: commits are attributed to your name and email on GitHub.

---

Netlify Deploy Problems

Build fails with ".NET SDK not found"

Symptom: Netlify deploy log shows:

/usr/local/bin/build: line 1: dotnet: command not found

or:

MSBUILD : error MSB1009: Project file does not exist.

Cause: Netlify's build environment does not include .NET by default. The netlify.toml must specify the SDK version.

Fix:

1. Open netlify.toml in the repository

2. Confirm it has:

   [build.environment]

     DOTNET_VERSION = "9.0.x"
   

3. If missing, add it

4. Commit and push

5. Netlify rebuilds automatically

Verify: the deploy log shows the .NET SDK being installed before the build.

Build fails with "Binary not found"

Symptom: the deploy log shows:

./bin/DaxPro: No such file or directory

Cause: the build command references a binary name that does not match your .csproj.

Fix:

1. Open Dax.csproj (or your .csproj file)

2. Find — this is the binary name

3. Open netlify.toml

4. Update the build command to use the correct name:

   [build]

     command = "dotnet publish -c Release -o bin && ./bin/YourBinaryName build"
   

5. Commit and push

Verify: the deploy log shows the binary building and running.

Deploy hangs or times out

Symptom: the Netlify deploy is "in progress" for more than 10 minutes.

Cause: Netlify has a build timeout (typically 15 minutes on the free plan). Something in the build is extremely slow.

Fix:

1. Open the deploy log to see where it hangs

2. Common hang points:

- NuGet restore — usually fast; a slow network on Netlify's side is rare but possible

- dotnet publish — the build compiles C#; first build may take 90 seconds

- dax build — should take under 5 seconds; if it hangs, a file read is blocking

3. Cancel the deploy (Netlify dashboard → Deploys → Cancel)

4. Retry the deploy

5. If it consistently hangs, contact Netlify support with the deploy log

Verify: the deploy completes in under 5 minutes.

Deploy succeeds but site shows 404

Symptom: the deploy completes (green check) but the site URL shows "Page not found."

Cause: the publish directory in netlify.toml is wrong.

Fix:

1. Open netlify.toml

2. Confirm:

   [build]

     publish = "site"
   

3. If publish points to something else (dist, public, bin), change it to site

4. Commit and push

Verify: the site loads at the Netlify URL.

Deploy succeeds but old content persists

Symptom: the deploy is green, but the site still shows old content after a hard-refresh.

Cause: CDN cache. Netlify caches assets; a deploy invalidates the cache but propagation takes a few minutes.

Fix:

1. Wait 2–3 minutes

2. Hard-refresh (Ctrl + Shift + R)

3. If still stale, trigger a cache-clearing rebuild:

- Netlify → Deploys → Trigger deploy → Clear cache and deploy site

Verify: the new content appears.

---

Decap CMS Problems

/admin/ shows a blank page

Symptom: navigating to /admin/ shows a white page. Nothing loads.

Cause: the Decap CMS JavaScript failed to load, or the admin/index.html file is missing.

Fix:

1. Open DevTools (F12) → Console

2. Check for errors:

- 404 on /admin/index.html — the file is missing from public/admin/. Add it.

- 404 on decap-cms.js — the CDN is unreachable. Try again in a few minutes.

- CSP violation — a Content Security Policy header is blocking the script. Remove the CSP header or allow unpkg.com.

3. If the console shows a network error, the fix is usually re-deploying.

Verify: the login screen appears at /admin/.

Login fails with "invalid credentials"

Symptom: entering email and password returns an error.

Cause: the password is wrong, the user is not invited, or the Identity service is not enabled.

Fix:

1. Check the Identity user list in Netlify → Identity. Is your email there?

2. If not, invite yourself: Identity → Invite users → enter email

3. Check the invitation email — did you accept it and set a password?

4. If you accepted but forgot the password, use Forgot password on the login screen

5. If the site owner cannot log in either, check whether Git Gateway and Identity are enabled in Netlify

Verify: login succeeds and the CMS dashboard appears.

Publishing fails with "Failed to persist entry"

Symptom: clicking Publish shows an error.

Cause: Git Gateway cannot commit to GitHub.

Fix:

1. Open Netlify → Identity

2. Confirm Git Gateway is enabled

3. Check the GitHub access token:

- Netlify → Identity → Git Gateway → GitHub access token

- The token must be present and not expired

4. If the token is expired, regenerate on GitHub and paste the new one

5. Retry the publish

Verify: publishing succeeds and a new commit appears on GitHub within 30 seconds.

Media library is empty

Symptom: clicking an image field shows "No images found." Uploaded images are missing.

Cause: the media library reads from public/images/ via Git Gateway. If the folder is empty or Git Gateway cannot read it, the library is empty.

Fix:

1. Confirm public/images/ exists in the repository and has files

2. Confirm config.yml has:

   media_folder: "public/images"

   public_folder: "/images"
   

3. Confirm Git Gateway has read access (same token as above)

4. Re-login to the CMS

Verify: the media library shows existing images and allows uploads.

Editor sees "Unauthorized" or "403"

Symptom: login succeeds, but the editor cannot view or publish content.

Cause: the editor is authenticated but lacks Git Gateway permission.

Fix:

1. Confirm Git Gateway is enabled in Netlify Identity

2. Confirm the token has repo scope

3. If the editor was recently invited, wait a minute for the invitation to propagate

4. If the problem persists, remove and re-invite the editor

Verify: the editor can view and publish content.

---

DNS and HTTPS Problems

Domain verification stays "Awaiting external DNS"

Symptom: you added the custom domain in Netlify, but it stays in "Awaiting external DNS" for hours.

Cause: the DNS records at your registrar are wrong, or Cloudflare proxy is enabled.

Fix:

1. In your DNS provider (Cloudflare, Namecheap, etc.), verify the A record points to 75.2.60.5

2. Verify the CNAME www points to your-site.netlify.app

3. If using Cloudflare, set Proxy status to DNS only (gray cloud, not orange)

4. Check propagation at dnschecker.org

5. Wait 10 more minutes, then check Netlify again

Verify: Netlify shows the domain as Verified.

HTTPS certificate fails to provision

Symptom: domain is verified, but the HTTPS certificate never issues.

Cause: CAA records block Let's Encrypt, or the domain is proxied, or DNS has not fully propagated.

Fix:

1. Check for CAA records on your domain:

   dig CAA yourdomain.com

   

2. If CAA records exist, they must include letsencrypt.org. Add a record:

- Type: CAA

- Name: @

- Value: 0 issue "letsencrypt.org"

3. Disable Cloudflare proxy (gray cloud, not orange)

4. In Netlify → Domain management, click Renew certificate

Verify: the padlock icon appears in the browser address bar.

HTTP loads but HTTPS shows an error

Symptom: http://yourdomain.com works, but https://yourdomain.com shows a certificate error.

Cause: the certificate has not been provisioned yet, or it expired.

Fix:

1. Wait 10 minutes — Let's Encrypt provisioning is fast but not instant

2. If it has been over an hour, check the domain in Netlify → Domain management. If HTTPS shows "provisioning failed," see the previous section

3. If the certificate expired, Netlify should auto-renew 30 days before expiry. If it has not, click Renew certificate manually

Verify: the browser shows the padlock with no warnings.

---

Content Rendering Problems

A page is empty

Symptom: the URL loads, but the page body is blank.

Cause: the frontmatter exists but the layout is wrong, or the layout cannot find the expected data.

Fix:

1. Check the page's frontmatter — does layout: match an existing file in templates/layouts/?

2. If layout: home.dax but home.dax does not exist, the page renders empty. Change to an existing layout or create the missing file.

3. Check whether {{ content }} is present in the layout. If not, the Markdown body does not render.

4. Check whether the partial includes resolve — a missing {% include %} renders a comment, not an error.

Verify: the page renders its content.

A section on the homepage is empty

Symptom: the homepage loads, but one section (e.g., pricing, trust, showcase) is blank.

Cause: the frontmatter for that section is missing or malformed.

Fix:

1. Open content/index.md

2. Check that the section key exists (e.g., pricing:)

3. Check that all required sub-keys exist (tier1.name, tier1.price, etc.)

4. If a key is missing, the template renders empty for that field. Add the key or add {% if %} guards in the template.

Verify: the section renders correctly.

A collection listing is empty

Symptom: /posts/ or /services/ loads but shows no items.

Cause: the collection folder is empty, or the controller file is missing, or the items do not have the expected frontmatter.

Fix:

1. Check content/posts/ — are there .md files?

2. Check content/posts.md — does it exist and have collection: "posts"?

3. Check one post's frontmatter — does it have title, date, description, layout: post.dax?

4. If the controller is missing, create it (see the Blog Controller chapter)

Verify: the listing shows items.

Tags return 404

Symptom: clicking a tag chip on a post goes to /tags/sometag/ and returns 404.

Cause: the tag is uppercase or has spaces. The tag page is generated at the lowercased, hyphenated URL, but the tag chip links to the raw tag.

Fix:

1. Open the post's frontmatter

2. Change the tag to lowercase, with hyphens for spaces:

   tags: ["DotNet"]           # wrong

   tags: ["dotnet"]           # correct
   tags: ["content migration"] # wrong
   tags: ["content-migration"] # correct
   

3. Rebuild and deploy

Verify: the tag chip links to an existing page.

---

Template Problems

{% include %} does not render anything

Symptom: a partial include outputs nothing. The section is missing entirely.

Cause: the partial file does not exist at the expected path.

Fix:

1. Check that the file exists: templates/partials/{context}/{name}.dax

2. Check the include path matches: {% include {context}/{name}.dax %}

3. Check for typos in either the include or the filename

4. Rebuild

Verify: the partial renders.

Nested list renders nothing

Symptom: a loop over a nested list ({% for item in section.items %}) outputs nothing, even though the YAML has items.

Cause: the YAML structure is not what the parser expects. The parser supports only two levels of nesting. Three levels or more fail silently.

Fix:

1. Count the nesting depth of your YAML:

   section:           # level 1

     items:           # level 2
       - title: "..." # level 3
         nested:      # level 4 (unsupported)
   

2. If the depth is more than 2, flatten the data:

- Move the deeper level into a separate _data/*.yaml file

- Or restructure so the nesting is only 2 levels

3. Rebuild

Verify: the loop outputs items.

---

How to Read Logs

The log is where the real error lives. Every symptom in this chapter has a log entry that points to the cause.

Netlify build log

1. Open Netlify dashboard

2. Click Deploys

3. Click the failed deploy

4. The log shows each step:

- SDK installation

- NuGet restore

- dotnet publish

- dax build

- Deploy to CDN

5. Scroll to the last few lines. The error is usually the last non-empty line before the failure summary.

GitHub Actions log (if using GitHub Pages)

1. Open the repository on GitHub

2. Click Actions

3. Click the failed workflow run

4. Click the failed job

5. Expand each step to see its log

Browser console

1. Open the site in a browser

2. Press F12

3. Click Console

4. Errors and warnings appear here

5. Common errors:

- 404 on scripts or stylesheets

- CSP violations

- JavaScript exceptions

Netlify Function log (if using functions)

Dax Pro does not use Netlify Functions by default. If you added one, its logs are in Netlify → Functions → click the function → Logs.

---

Getting Help

If you have tried the fixes in this chapter and the problem persists:

1. Check the GitHub repository — github.com/mesinkasir/dax

2. Email support — [email protected] with:

- The exact error message (copy from the log, do not paraphrase)

- The command or action that produced it

- The relevant file content (post frontmatter, netlify.toml, etc.)

3. Fiverr consultation — fiverr.com/creativitas for custom debugging sessions

Do not send a screenshot of the error alone. Screenshots do not allow copy-paste of the error text. Send text.

---

What You Have Now

After this chapter, you can:

• ✅ Diagnose and fix the ten most common local build errors
• ✅ Fix Git authentication and push issues
• ✅ Resolve Netlify deploy failures
• ✅ Recover from Decap CMS login and publish problems
• ✅ Fix DNS and HTTPS issues
• ✅ Diagnose content rendering problems (empty pages, missing sections, 404 tags)
• ✅ Fix template issues (missing partials, unsupported nesting)
• ✅ Read logs to find the actual error
• ✅ Know where to get help when self-help fails

Troubleshooting is not about memorizing fixes. It is about knowing where to look and how to isolate the problem. This chapter gives you the map. The rest is practice.

The next chapter is Updates — how to update Dax Pro when a new version is released, without losing your customizations.

→ Continue to Updates