From 741db4e1054ebd88c7a289a4aae757ae38d487bc Mon Sep 17 00:00:00 2001
From: Jason Altekruse <jaltekruse@usgs.gov>
Date: Wed, 29 Mar 2023 16:32:38 -0600
Subject: [PATCH] add note about unicode error and work around for windows
 users

---
 docs/pages/Building-&-Running.md        | 4 ++++
 etc/examples/7-disaggregation/README.md | 6 ++++++
 2 files changed, 10 insertions(+)

diff --git a/docs/pages/Building-&-Running.md b/docs/pages/Building-&-Running.md
index df8228892..35d8685bc 100644
--- a/docs/pages/Building-&-Running.md
+++ b/docs/pages/Building-&-Running.md
@@ -90,6 +90,10 @@ Disaggregations build on and output `HazardCalc` results along with other disagg
 files. Disaggregations also have some independent
 [configuration](./Calculation-Configuration.md#calculation-configuration-parameters) options.
 
+Windows users may run into errors caused by unicode characters in the disaggregation configuration
+options. As a work around, add `-Dfile.encoding="UTF-8"` to the java call (see
+[example 7](../../etc/examples/7-disaggregation/README.md) for more details).
+
 ## Customizing Code
 
 Whereas *nshmp-haz* contains code to run command line applications and web services, model
diff --git a/etc/examples/7-disaggregation/README.md b/etc/examples/7-disaggregation/README.md
index e6578d88e..1cf4ab997 100644
--- a/etc/examples/7-disaggregation/README.md
+++ b/etc/examples/7-disaggregation/README.md
@@ -11,6 +11,12 @@ to create a second system alias:
 alias disagg='java -Xms4g -Xmx8g -cp /path/to/nshmp-haz/build/libs/nshmp-haz.jar gov.usgs.earthquake.nshmp.DisaggCalc'
 ```
 
+Note for Windows users: running `nshmp-haz` in command prompt, Power Shell, or GitBash may
+result in errors caused by the unicode characters in the disaggregation configuration parameters.
+For example: `java.lang.IllegalArgumentException: Invalid ? [0.0]`. To avoid this, try adding
+'`-Dfile.encoding="UTF-8"`' before `-cp` in the disagg alias shown above. This error does not
+seem to occur if `nshmp-haz` is built and run in the Windows Subsystem for Linux (WSL).
+
 The command line arguments for `DisaggCalc` are the same as those for `HazardCalc`. The target
 return period for a disaggregation is specified in the config
 [`disagg.returnPeriod`](../../../docs/pages/Calculation-Configuration.md#calculation-configuration-parameters)
-- 
GitLab