Sitecore JavaScript SDK (JSS) ヘッドレスのトラブルシューティング


Sitecore JavaScript SDK (JSS) ヘッドレス(Headless)のトラブルシューティングを記載します

the filename, directory name, or volume label syntax is incorrect.


jss start などでタスクの実行中に発生。


npm のバージョンが 8.13.0 で発生


npm のバージョンを 8.12.2 など 8.12 系にする。

The environment file .\src\rendering.env does not exist


.\init.ps1 時にエラーが発生することがあります。エラー画面とメッセージは次の通り

The environment file .\src\rendering\.env does not exist
At C:\Users\nnasaki\Documents\WindowsPowerShell\Modules\SitecoreDockerTools\10.2.7\Public\Set-EnvFileVariable.ps1:45 ch
+         throw "The environment file $Path does not exist"
+         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : OperationStopped: (The environment... does not exist:String) [], RuntimeException
    + FullyQualifiedErrorId : The environment file .\src\rendering\.env does not exist


これはinitする前の dotnet new でプロジェクト作成時にラテン文字以外が含まれているためです。この時は10-2としていたため、Transformed to valid JSS project name の箇所でエラーとなっていました

PS C:\Users\nnasaki\source\headless> dotnet new sitecore.nextjs.gettingstarted -n 10-2
The template "Sitecore Simple Container-based Next.js Solution" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on 10-2\10-2.sln...
  Determining projects to restore...
C:\Users\nnasaki\source\headless\10-2\src\platform\Platform.csproj : warning NU1603: Sitecore.Kernel 10.2.0 depends on Sitecore.Nexus.Consumption (>= 1.4.0) but Sitecore.Nexus.Consumption 1.4.0 was not found. An approximate best match of Sitecore.Nexus.Consumption 1.4.2 was resolved. [C:\Users\nnasaki\source\headless\10-2\10-2.sln]
  Restored C:\Users\nnasaki\source\headless\10-2\src\platform\Platform.csproj (in 3.24 sec).
Restore succeeded.

Template is configured to run the following action:
Description: Restores dotnet local tools for the solution.
Manual instructions: Run 'dotnet tool restore'
Actual command: dotnet tool restore
Do you want to run this action [Y(yes)|N(no)]?
Running command 'dotnet tool restore'...
Command succeeded.

Template is configured to run the following action:
Description: Initializes the JSS project.
Manual instructions: Run 'create-jss-project.ps1'
Actual command: powershell -File create-jss-project.ps1
Do you want to run this action [Y(yes)|N(no)]?
Running command 'powershell -File create-jss-project.ps1'...
Adding JSS sample to solution via 'jss create'...
Creating JSS Project for 10-2
Transformed to valid JSS project name
Command failed.
Output from command:
JSS CLI is running in global mode because it was not installed in the local node_modules folder.
jss create <name> <template>

Creates a new JSS application based on one of the sample apps.

  name      The name of the app to create.                   [string] [required]
  template  The template to create the app from; corresponds to folders in
                                                             [string] [required]

  --version         Show version number                                [boolean]
  --help            Show help                                          [boolean]
  --hostName        Sets the host name of the Sitecore site if this app is
                    deployed to Sitecore. Defaults to '$name.dev.local' [string]
  --repository, -r  Configures the GitHub repository to get the app from. Used
                    to create from your own custom templates. Ex:
                    myOrg/myRepository        [string] [default: "Sitecore/jss"]
  --branch, -b      Configures the GitHub branch to get the app from. Used to
                    create from your own custom templates. Ex: beta
                                                    [string] [default: "master"]
  --source, -s      Sources the app template from a local filesystem path,
                    instead of a GitHub repository. Good for private templates.
  --proxy           Specify a HTTP proxy when downloading templates.    [string]

Not enough non-option arguments: got 1, need at least 2
Move-Item : Cannot bind argument to parameter 'Path' because it is an empty string.
At C:\Users\nnasaki\source\headless\10-2\create-jss-project.ps1:46 char:26
+         Move-Item -Force $jssProjectName rendering | Out-Null
+                          ~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Move-Item], ParentContainsErrorRecordException
    + FullyQualifiedErrorId : ParameterArgumentValidationErrorEmptyStringNotAllowed,Microsoft.PowerShell.Commands.Move


dotnet new sitecore.nextjs.gettingstarted -n MyProject2のように必ず英文字で始まるプロジェクト名にしてください。ドキュメントにも以下のように記載されています。

Do not use non-Latin characters in the project/folder name. Using non-Latin characters can give unexpected results because of character limitations in Docker registry names and URLs.