Fix the problem you can see, not the one you guess

project.json not found

Likely cause: you are not running the command from a Nova project root, or the path you supplied does not point at a folder that contains project.json.

Fix:

PS> Set-Location ~/Work/<YourProjectName>
PS> Get-NovaProjectInfo

% cd ~/Work/<YourProjectName>
% nova info

If you are targeting a different location explicitly, use:

PS> Get-NovaProjectInfo -Path ~/Work/<YourProjectName>

Success looks like: Get-NovaProjectInfo returns a project object instead of throwing Not a project folder. project.json not found.

See the project.json reference

% nova init some/path does not work

Likely cause: positional paths are intentionally rejected by the CLI.

Fix:

% nova init --path some/path
% nova init --example --path some/path

Success looks like: Nova accepts the command, prompts for project details, and creates the new scaffold under the specified parent directory.

See the scaffold quickstart

% nova bump says the repository has no commits yet

Likely cause: the current folder is a Git repository, but it has not recorded its first commit yet.

Fix:

% git add .
% git commit -m "feat: initial project scaffold"
% nova bump --what-if

Success looks like: % nova bump --what-if shows a planned semantic version update instead of throwing the “repository has no commits yet” error.

See version bump rules

The module does not reload after build

Likely cause: PowerShell still has the older module loaded in memory.

Fix:

PS> $project = Get-NovaProjectInfo
PS> Remove-Module $project.ProjectName -ErrorAction SilentlyContinue
PS> Invoke-NovaBuild
PS> Import-Module $project.OutputModuleDir -Force

% nova build
pwsh -NoLogo -Command 'Import-Module (Get-NovaProjectInfo).OutputModuleDir -Force; Get-Command -Module (Get-NovaProjectInfo).ProjectName'

Success looks like: the imported module reflects your latest source changes.

See the reload guide

Tests ran but I cannot find the results

Likely cause: you expected test output in a different location, or you ran Pester directly instead of through Nova.

Fix: use the Nova workflow and check:

artifacts/UnitTestResults.xml
artifacts/TestResults.xml

Success looks like: artifacts/UnitTestResults.xml exists after a successful Invoke-NovaTest or % nova test run, and artifacts/TestResults.xml exists after a successful Test-NovaBuild or % nova test --build run.

See the test workflow

Build errors point into the generated .psm1

Likely cause: the generated module is showing you the combined output, but you need to map the error back to source files.

Fix: keep SetSourcePath enabled in project.json.

{
  "SetSourcePath": true
}

Success looks like: the generated module contains # Source: markers that point back to the originating files under src/.

See top-level build settings

Install-NovaCli says it is for macOS/Linux only

Likely cause: that is the current intended behavior. The standalone launcher is for macOS/Linux shell use.

Fix: on Windows, import the module and use the PowerShell cmdlets directly. The standalone nova launcher is a separate macOS/Linux install path, not something that appears automatically after Import-Module.

PS> Import-Module NovaModuleTools
PS> Get-NovaProjectInfo
PS> Invoke-NovaBuild

Success looks like: the NovaModuleTools cmdlets work in your PowerShell session on Windows, and you do not need a separate launcher install for that workflow.

See entrypoint guidance

Upload target URL is missing

Likely cause: you ran Deploy-NovaPackage without -Url and without package or repository upload settings that resolve to a target URL.

Fix: either pass -Url directly or configure Package.RepositoryUrl or Package.Repositories[].Url.

PS> Deploy-NovaPackage -Url 'https://packages.example/raw/'

% nova deploy --url https://packages.example/raw/

# or in project.json

{
  "Package": {
    "RepositoryUrl": "https://packages.example/raw/"
  }
}

Success looks like: upload resolves a concrete destination URL and starts sending matching artifacts.

See upload target resolution

Raw upload auth does not work

Likely cause: the header name, scheme, token value, or environment-variable usage does not match what the raw endpoint expects.

Fix checklist:

• Make sure TokenEnvironmentVariable contains the variable name, not the secret value itself.
• For bearer auth, use HeaderName = "Authorization" and Scheme = "Bearer".
• For custom API keys, use the exact header name the server expects.
• For Basic auth, put the Base64-encoded username:password value in the environment variable and use Scheme = "Basic".

Success looks like: the raw endpoint accepts the request and upload returns result objects with HTTP status codes instead of authentication failures.

See package auth settings

Package output contains both versioned and latest artifacts

Likely cause: Package.Latest is enabled.

Fix: if you only want versioned files, remove the setting or set it to "never".

{
  "Package": {
    "Latest": "never"
  }
}

Success looks like: the next package run creates only the normal versioned artifacts.

See package output behavior

I expected publish, but I only created a package

Likely cause: you used New-NovaModulePackage when you actually wanted Deploy-NovaPackage, Publish-NovaModule, or Invoke-NovaRelease.

Fix: choose the command based on the outcome you need:

• package file only: New-NovaModulePackage
• raw HTTP upload: Deploy-NovaPackage
• PowerShell repository publish: Publish-NovaModule
• version bump + publish orchestration: Invoke-NovaRelease

Success looks like: the workflow result matches the actual destination you intended.

See the delivery command comparison