When linking a Scala.js application, either directly through fastOptJS/fullOptJS or indirectly through run or test, Scala.js can sometimes report linking errors.They look like the following:

  1. [info] Fast optimizing .../helloworld/target/scala-2.12/helloworld-fastopt.js
  2. [error] Referring to non-existent method scala.concurrent.impl.Promise$CompletionLatch.releaseShared(scala.Int)scala.Boolean
  3. [error]   called from scala.concurrent.impl.Promise$CompletionLatch.apply(scala.util.Try)scala.Unit
  4. [error]   called from scala.concurrent.impl.Promise$CompletionLatch.apply(java.lang.Object)java.lang.Object
  5. [error] ...
  6. [error] There were linking errors
  7. [error] (helloworld/compile:fastOptJS) There were linking errors
  8. [error] Total time: 2 s, completed Sep 13, 2019 1:30:39 PM

This means that, as Scala.js was analyzing the program for all classes and methods reachable from the main method (or from the tests), if found a call to a method that does not exist, or a new for a class that does not exist, etc.

Linking errors can have several root causes, which we detail here.The appropriate fix will depend on what the root cause is.

Depending on a JVM library instead of a JS library

A common cause for linking errors is to use %% instead of %%% when depending on another Scala.js library.Having the JVM version of a library on the classpath will allow compilation to succeed, but linking will fail.For example, with the following setting:

  1. libraryDependencies += "io.suzaku" %% "boopickle" % "1.3.1"

and the following code:

  1. import boopickle.Default._
  3. val data = Seq("Hello", "World!")
  4. val buf = Pickle.intoBytes(data)

compilation will succeed but linking will fail with:

  1. [error] Referring to non-existent class boopickle.Default$
  2. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  3. [error]   called from core module module initializers
  4. [error] involving instantiated classes:
  5. [error]   helloworld.HelloWorld$
  6. [error] Referring to non-existent class boopickle.PickleState$
  7. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  8. [error]   called from core module module initializers
  9. [error] involving instantiated classes:
  10. [error]   helloworld.HelloWorld$
  11. [error] Referring to non-existent method boopickle.PickleState$.pickleStateSpeed()boopickle.PickleState
  12. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  13. [error]   called from core module module initializers
  14. [error] involving instantiated classes:
  15. [error]   helloworld.HelloWorld$
  16. [error] Referring to non-existent method boopickle.Default$.stringPickler()boopickle.Pickler
  17. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  18. [error]   called from core module module initializers
  19. [error] involving instantiated classes:
  20. [error]   helloworld.HelloWorld$
  21. [error] Referring to non-existent method boopickle.Default$.Pickle()boopickle.PickleImpl$
  22. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  23. [error]   called from core module module initializers
  24. [error] involving instantiated classes:
  25. [error]   helloworld.HelloWorld$
  26. [error] Referring to non-existent method boopickle.Default$.iterablePickler(boopickle.Pickler,scala.collection.generic.CanBuildFrom)boopickle.Pickler
  27. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  28. [error]   called from core module module initializers
  29. [error] involving instantiated classes:
  30. [error]   helloworld.HelloWorld$
  31. [error] There were linking errors

Hint to recognize this cause

If the Referring to non-existent lines mention a library that you depend on, and the first corresponding called from lines mention your code, it is very likely that an erroneous %% is the cause.

Solution

Use %%% instead of %% when depending on other Scala.js librarys:

  1. libraryDependencies += "io.suzaku" %%% "boopickle" % "1.3.1"
  1. [info] Fast optimizing .../helloworld/target/scala-2.12/helloworld-fastopt.js
  2. [success] Total time: 3 s, completed Sep 13, 2019 1:44:25 PM

Using blocking APIs (e.g., Await.result)

The JavaScript platform does not support blocking at all.Consequently, trying to use blocking APIs such Await.result is not supported, and will result in a linking error.A typical example was shown in the introduction, and is reproducible with the following code:

  1. import scala.concurrent.{Await, Future}
  2. import scala.concurrent.ExecutionContext.Implicits.global
  3. import scala.concurrent.duration.Duration
  5. val f = Future { 5 }
  6. println(Await.result(f, Duration.Inf))

which yields

  1. [error] Referring to non-existent method scala.concurrent.impl.Promise$CompletionLatch.releaseShared(scala.Int)scala.Boolean
  2. [error]   called from scala.concurrent.impl.Promise$CompletionLatch.apply(scala.util.Try)scala.Unit
  3. [error]   called from scala.concurrent.impl.Promise$CompletionLatch.apply(java.lang.Object)java.lang.Object
  4. [error]   called from scala.util.Success.$$anonfun$map$1(scala.Function1)java.lang.Object
  5. [error]   called from scala.util.Success.map(scala.Function1)scala.util.Try
  6. [error]   called from scala.concurrent.Future.$$anonfun$map$1(scala.Function1,scala.util.Try)scala.util.Try
  7. [error]   called from scala.concurrent.impl.Promise$DefaultPromise.$$anonfun$map$1(scala.Function1,scala.util.Try)scala.util.Try
  8. [error]   called from scala.concurrent.Future.map(scala.Function1,scala.concurrent.ExecutionContext)scala.concurrent.Future
  9. [error]   called from scala.concurrent.impl.Promise$KeptPromise$Successful.map(scala.Function1,scala.concurrent.ExecutionContext)scala.concurrent.Future
  10. [error]   called from scala.concurrent.Future$.apply(scala.Function0,scala.concurrent.ExecutionContext)scala.concurrent.Future
  11. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  12. [error]   called from core module module initializers

and other errors.

Hint to recognize this cause

If the Referring to non-existent line mentions CompletionLatch, it is probably related to trying to block on a Future.

Solution

Always use asynchronous combinators, such as map, filter, flatMap, foreach, and/or for comprehensions, when using Future.Do not use scala.concurrent.Await.

Using unsupported JDK libraries (possibly transitively)

Scala.js reimplements parts of the JDK libraries, but not everything is supported.For example, the following code

  1. println(new java.io.File("foo.txt").exists())

which directly uses java.io.File, results in

  1. [error] Referring to non-existent class java.io.File
  2. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  3. [error]   called from core module module initializers
  4. [error] involving instantiated classes:
  5. [error]   helloworld.HelloWorld$
  6. [error] Referring to non-existent method java.io.File.exists()scala.Boolean
  7. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  8. [error]   called from core module module initializers
  9. [error] involving instantiated classes:
  10. [error]   helloworld.HelloWorld$
  11. [error] Referring to non-existent method java.io.File.<init>(java.lang.String)
  12. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  13. [error]   called from core module module initializers
  14. [error] involving instantiated classes:
  15. [error]   helloworld.HelloWorld$
  16. [error] There were linking errors

The following code indirectly uses java.io.File through scala.io:

  1. val src = scala.io.Source.fromFile("foo.txt", "UTF8")

yields

  1. [error] Referring to non-existent class java.io.File
  2. [error]   called from scala.io.Source$.fromFile(java.lang.String,scala.io.Codec)scala.io.BufferedSource
  3. [error]   called from scala.io.Source$.fromFile(java.lang.String,java.lang.String)scala.io.BufferedSource
  4. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  5. [error]   called from core module module initializers
  6. [error]   ...
  7. [error] There were linking errors

Hint to recognize this cause

If the Referring to non-existent line mentions a class from the java.* packages, you are probably trying to use an unsupported API.

Solution

Some areas of the JDK libraries are not provided by the core distribution, but are provided by third-party libraries.For example, the java.util.Locale API is provided by scala-java-locales.In that case, adding the relevant dependency can solve the problem:

  1. libraryDependencies += "io.github.cquiroz" %%% "scala-java-locales" % "0.5.2-cldr31"

You can find a list of JDK extensions in the Scala libraries list.

If the API you want to use is not provided by any third party (e.g., java.io.File), then you are out of luck.You must avoid that API, possibly using a JavaScript library instead (e.g., the fs module of Node.js).

Incremental compilation gone wrong

Sometimes, the incremental compiler of Scala, called Zinc and used by most build tools, exhibits under-compilation bugs.In that case, it is possible that the compiled .sjsir files are not completely in sync with the sources, and cannot be linked together.

  1. [error] Referring to non-existent method helloworld.Foo.bar(java.lang.String)scala.Unit
  2. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  3. [error]   called from core module module initializers
  4. [error] involving instantiated classes:
  5. [error]   helloworld.HelloWorld$
  6. [error] There were linking errors

Hint to recognize this cause

If the Referring to non-existent line mentions a class from your own codebase, you are probably facing an incremental compilation issue.

Solution

clean the project (or possibly all projects) in your sbt build (or the equivalent operation in other build tools).Retrying after clean should fix the issue.

Binary incompatibilities on the classpath

When depending on multiple libraries, it is possible that several of them transitively depend on two incompatible versions of the same library.Here is a hypothetical example:

  1. [error] Referring to non-existent method somelib.SomeLib.bar(java.lang.String)scala.Unit
  2. [error]   called from someotherlib.SomeOtherLib.foo(java.lang.String)scala.Unit
  3. [error]   called from helloworld.HelloWorld$.main()scala.Unit
  4. [error]   called from core module module initializers
  5. [error] ...
  6. [error] There were linking errors

In this case, someotherlib was compiled against some version x of somelib, but a new version y > x of somelib is used.In that new version, the method SomeLib.bar(String) does not exist anymore, causing a binary incompatibility.

Hint to recognize this cause

If the Referring to non-existent line mentions one library, and the first called from line mentions another library, there is probably a binary incompatibility between those two libraries.

This may also be detected and warned against by sbt itself, as evicted libraries.

Solution

Find a set of versions for your libraries that are binary compatible.This may involve upgrading and/or downgrading some of them.