Common issues

This document provides solutions to common setup, build, and runtime issues encountered when working with the TheExampleApp application. It is intended for developers responsible for maintaining and running the application locally.

Note: This repository is no longer officially maintained as of January 2023. Community support and self-service troubleshooting are the primary resources available.

Installation problems

A successful local installation depends on having the correct development environment and following the setup steps precisely. Most installation issues stem from an incorrect .NET Core SDK version.

Core Requirement: .NET Core 2.1 SDK

The application targets netcoreapp2.1, a specific version of the .NET Core framework. You must have the .NET Core 2.1 SDK installed on your development machine. Having newer versions of the .NET SDK installed is fine, but the 2.1 SDK is mandatory for this project to build and run.

<!-- TheExampleApp/TheExampleApp.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>
  ...
</Project>

If the correct SDK is not installed, you will encounter build failures. You can download archived versions of the .NET SDK from the official Microsoft website.

For a complete guide on setting up the project from scratch, please refer to the Local Setup Guide.

Dependency restoration failures

The project relies on NuGet for backend package management. The dotnet restore command, as mentioned in the README.md, is used to download and install these dependencies. Failures in this step will prevent the application from building.

NuGet package issues

The primary dependencies are defined in TheExampleApp/TheExampleApp.csproj:

<!-- TheExampleApp/TheExampleApp.csproj -->
<ItemGroup>
    <PackageReference Include="contentful.aspnetcore">
      <Version>3.3.6</Version>
    </PackageReference>
    <PackageReference Include="Markdig">
      <Version>0.15.4</Version>
    </PackageReference>
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.1.5" />
    <PackageReference Include="Microsoft.AspNetCore.Razor.Language" Version="2.1.2" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design">
      <Version>2.1.5</Version>
    </PackageReference>
</ItemGroup>

Common Causes for Failure:

• Network Connectivity/Firewall: Ensure you have an active internet connection and that your network firewall is not blocking access to nuget.org. In a corporate environment, you may need to configure a proxy for the NuGet CLI.
• Corrupt NuGet Cache: The local NuGet cache can sometimes become corrupted. Clearing it can resolve restoration issues. See the Clear and restore section for instructions.
• Package Version Conflicts: The project uses the Microsoft.AspNetCore.All metapackage, which bundles a specific set of framework libraries. While this simplifies dependency management, it can occasionally lead to conflicts if other packages require different versions of a transitive dependency. Given the age of the 2.1.5 version, this is less likely to be an issue unless new packages are introduced.

Note on Frontend Dependencies: The project uses Bower for frontend package management, but the bower.json file is empty. Therefore, no client-side packages need to be restored.

Runtime errors

Runtime errors typically occur after the application has successfully built but fails during startup or while handling a request. Most runtime issues in this application are related to its connection with the Contentful headless CMS.

Contentful connection errors

The application is critically dependent on a valid connection to the Contentful API. Configuration for this is managed in TheExampleApp/appsettings.json.

// TheExampleApp/appsettings.json
{
  "ContentfulOptions": {
    "DeliveryApiKey": "df2a18b8a5b4426741408fc95fa4331c7388d502318c44a5b22b167c3c1b1d03",
    "PreviewApiKey": "10145c6d864960fdca694014ae5e7bdaa7de514a1b5d7fd8bd24027f90c49bbc",
    "SpaceId": "qz0n5cdakyl9",
    "UsePreviewApi": false
  }
}

Key Configuration and Potential Issues:

Key	Purpose	Common Issue
DeliveryApiKey	API token for accessing published content.	An invalid or revoked key will result in 401 Unauthorized or 403 Forbidden errors from the Contentful API.
PreviewApiKey	API token for accessing draft/unpublished content.	An invalid key will cause errors when UsePreviewApi is true.
SpaceId	The unique identifier for your Contentful space.	An incorrect ID will result in 404 Not Found errors, as the application will be trying to access a space that doesn't exist.
UsePreviewApi	A boolean flag (true/false) that tells the SDK to use the Preview API instead of the Delivery API.	If true, the app will request draft content using the PreviewApiKey. If false, it will request published content with the DeliveryApiKey.

These settings are loaded at startup in Startup.cs:

// TheExampleApp/Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddContentful(Configuration);
    // ...
}

An invalid configuration will typically cause the application to throw exceptions when it first attempts to query Contentful, often resulting in an error page being displayed to the user. For more detailed troubleshooting, see Contentful Issues and the Contentful Setup Guide.

Missing configuration

If the appsettings.json file is missing or the ContentfulOptions section is removed, the application will fail at startup. The services.AddContentful(Configuration) extension method expects to bind the ContentfulOptions section to its configuration object. A missing section will result in a NullReferenceException or similar configuration-related error when the IContentfulClient is instantiated.

Port conflicts

As noted in the README.md, the application is expected to run on http://localhost:3000. If another service is already using this port, the Kestrel web server will fail to start, usually with an IOException indicating that the address is already in use.

To resolve this, you can either stop the other process or configure the application to use a different port. This can typically be done by modifying the Properties/launchSettings.json file (not included in the provided files, but standard for ASP.NET Core projects) or by using command-line arguments when running the application.

Build failures

Build failures occur when the dotnet build command fails, preventing the creation of a runnable application binary.

SDK version mismatches

As mentioned under Installation problems, the most common cause of build failure is a missing .NET Core 2.1 SDK. The build output will explicitly state that the framework Microsoft.NETCore.App, version 2.1.0 (or a compatible patch) was not found.

Error: The framework 'Microsoft.NETCore.App', version '2.1.0' was not found.

Ensure the .NET Core 2.1 SDK is installed to resolve this.

Missing dependencies

If dotnet restore was not run or failed silently, the build process will be unable to find the required package references (e.g., contentful.aspnetcore, Markdig). This will result in numerous compilation errors related to missing namespaces and types.

Solution: Always run dotnet restore successfully before attempting to build or run the project. For more advanced debugging techniques, refer to our Debugging Guide.

Quick fixes

Before diving into deep debugging, try these common quick fixes that resolve a majority of local environment issues.

Clear and restore

Corrupt build artifacts or a stale package cache can cause a wide range of inexplicable issues. Cleaning the project and restoring dependencies from scratch is a reliable first step.

Execute the following commands in your terminal from the solution's root directory:

# Removes all build artifacts (bin/ and obj/ folders)
dotnet clean

# Deletes and re-downloads all NuGet packages
dotnet restore

Configuration validation

Incorrect configuration is the leading cause of runtime errors. Use this checklist to validate your setup:

1. Verify appsettings.json: Ensure the file TheExampleApp/appsettings.json exists and is valid JSON.
2. Check Contentful Credentials:
   • Confirm that SpaceId, DeliveryApiKey, and PreviewApiKey match the values from your Contentful space's API keys section.
   • Be careful not to mix up the Delivery and Preview API keys.
3. Check UsePreviewApi Flag:
   • Set to false to view only published content.
   • Set to true to view draft content. Ensure the PreviewApiKey is correct if this is enabled.
4. Enable Editorial Features: For the full "edit" experience, remember to append ?editorial_features=enabled to the URL when running locally (e.g., http://localhost:3000?editorial_features=enabled). This enables the "Edit" buttons in the UI.