PROBLEMS 135 KB
Newer Older
Kim F. Storm's avatar
Kim F. Storm committed
1 2
Known Problems with GNU Emacs

3
Copyright (C) 1987-1989, 1993-1999, 2001-2019 Free Software Foundation,
4
Inc.
5 6 7
See the end of the file for license conditions.


Dave Love's avatar
#  
Dave Love committed
8
This file describes various problems that have been encountered
9 10
in compiling, installing and running GNU Emacs.  Try doing C-c C-t
and browsing through the outline headers.  (See C-h m for help on
11 12 13
Outline mode.)  Information about systems that are no longer supported,
and old Emacs releases, has been removed.  Consult older versions of
this file if you are interested in that information.
Dave Love's avatar
#  
Dave Love committed
14

15
* Mule-UCS doesn't work in Emacs 23 onwards
Dave Love's avatar
Dave Love committed
16 17 18

It's completely redundant now, as far as we know.

19
* Emacs startup failures
20

21
** Emacs fails to start, complaining about missing fonts.
22

23
A typical error message might be something like
24

25
  No fonts match ‘-*-fixed-medium-r-*--6-*-*-*-*-*-iso8859-1’
Kenichi Handa's avatar
Kenichi Handa committed
26

27
This happens because some X resource specifies a bad font family for
28
Emacs to use.  The possible places where this specification might be are:
Kenichi Handa's avatar
Kenichi Handa committed
29

Ivan Shmakov's avatar
Ivan Shmakov committed
30 31 32
  - in the X server resources database, often initialized from
    ~/.Xresources (use $ xrdb -query to find out the current state)

33
  - in your ~/.Xdefaults file
Kenichi Handa's avatar
Kenichi Handa committed
34

35
  - client-side X resource file, such as  ~/Emacs or
36
    /usr/share/X11/app-defaults/Emacs
Kenichi Handa's avatar
Kenichi Handa committed
37

38 39 40
One of these files might have bad or malformed specification of a
fontset that Emacs should use.  To fix the problem, you need to find
the problematic line(s) and correct them.
Kenichi Handa's avatar
Kenichi Handa committed
41

Ivan Shmakov's avatar
Ivan Shmakov committed
42 43 44 45 46 47
After correcting ~/.Xresources, the new data has to be merged into the
X server resources database.  Depending on the circumstances, the
following command may do the trick.  See xrdb(1) for more information.

  $ xrdb -merge ~/.Xresources

48
** Emacs aborts while starting up, only when run without X.
Kenichi Handa's avatar
Kenichi Handa committed
49

50 51 52 53 54 55 56 57 58
This problem often results from compiling Emacs with GCC when GCC was
installed incorrectly.  The usual error in installing GCC is to
specify --includedir=/usr/include.  Installation of GCC makes
corrected copies of the system header files.  GCC is supposed to use
the corrected copies in preference to the original system headers.
Specifying --includedir=/usr/include causes the original system header
files to be used.  On some systems, the definition of ioctl in the
original system header files is invalid for ANSI C and causes Emacs
not to work.
Kenichi Handa's avatar
Kenichi Handa committed
59

60 61 62 63
The fix is to reinstall GCC, and this time do not specify --includedir
when you configure it.  Then recompile Emacs.  Specifying --includedir
is appropriate only in very special cases and it should *never* be the
same directory where system header files are kept.
Kenichi Handa's avatar
Kenichi Handa committed
64

65
** Emacs does not start, complaining that it cannot open termcap database file.
Kenichi Handa's avatar
Kenichi Handa committed
66

67 68 69 70
If your system uses Terminfo rather than termcap (most modern
systems do), this could happen if the proper version of
ncurses is not visible to the Emacs configure script (i.e. it
cannot be found along the usual path the linker looks for
71
libraries).  It can happen because your version of ncurses is
72
obsolete, or is available only in form of binaries.
Kenichi Handa's avatar
Kenichi Handa committed
73

74 75 76 77
The solution is to install an up-to-date version of ncurses in
the developer's form (header files, static libraries and
symbolic links); in some GNU/Linux distributions (e.g. Debian)
it constitutes a separate package.
Kenichi Handa's avatar
Kenichi Handa committed
78

79
** Emacs 20 and later fails to load Lisp files at startup.
80

81
The typical error message might be like this:
82

83
  "Cannot open load file: fontset"
84

85 86 87 88
This could happen if you compress the file lisp/subdirs.el.  That file
tells Emacs what are the directories where it should look for Lisp
files.  Emacs cannot work with subdirs.el compressed, since the
Auto-compress mode it needs for this will not be loaded until later,
89
when your .emacs file is processed.  (The package 'fontset.el' is
90 91
required to set up fonts used to display text on window systems, and
it's loaded very early in the startup procedure.)
92

93 94
Similarly, any other .el file for which there's no corresponding .elc
file could fail to load if it is compressed.
Dave Love's avatar
Dave Love committed
95

96
The solution is to uncompress all .el files that don't have a .elc file.
Kenichi Handa's avatar
Kenichi Handa committed
97

98
Another possible reason for such failures is stale *.elc files
99
lurking somewhere on your load-path -- see the next section.
Dave Love's avatar
Dave Love committed
100

101
** Emacs prints an error at startup after upgrading from an earlier version.
Dave Love's avatar
Dave Love committed
102

103
An example of such an error is:
Dave Love's avatar
Dave Love committed
104

105
  x-complement-fontset-spec: "Wrong type argument: stringp, nil"
Dave Love's avatar
Dave Love committed
106

107 108 109
This can be another symptom of stale *.elc files in your load-path.
The following command will print any duplicate Lisp files that are
present in load-path:
Dave Love's avatar
Dave Love committed
110

Glenn Morris's avatar
Glenn Morris committed
111
    emacs -batch -f list-load-path-shadows
Dave Love's avatar
Dave Love committed
112

113 114 115
If this command prints any file names, some of these files are stale,
and should be deleted or their directories removed from your
load-path.
116

117
* Crash bugs
118

119
** Emacs crashes when running in a terminal, if compiled with GCC 4.5.0
120

121 122
This version of GCC is buggy: see

123 124
  https://debbugs.gnu.org/6031
  https://gcc.gnu.org/bugzilla/show_bug.cgi?id=43904
125 126 127 128

You can work around this error in gcc-4.5 by omitting sibling call
optimization.  To do this, configure Emacs with

129
 ./configure CFLAGS="-g -O2 -fno-optimize-sibling-calls"
130

131 132 133 134 135
** Emacs compiled with GCC 4.6.1 crashes on MS-Windows when C-g is pressed

This is known to happen when Emacs is compiled with MinGW GCC 4.6.1
with the -O2 option (which is the default in the Windows build).  The
reason is a bug in MinGW GCC 4.6.1; to work around, either add the
136 137
'-fno-omit-frame-pointer' switch to GCC or compile without
optimizations ('--no-opt' switch to the configure.bat script).
138

139
** Emacs crashes in x-popup-dialog.
140

141 142
This can happen if the dialog widget cannot find the font it wants to
use.  You can work around the problem by specifying another font with
143
an X resource--for example, 'Emacs.dialog*.font: 9x15' (or any font that
144
happens to exist on your X server).
Dave Love's avatar
Dave Love committed
145

146
** Emacs crashes when you use Bibtex mode.
Dave Love's avatar
Dave Love committed
147

148
This happens if your system puts a small limit on stack size.  You can
149
prevent the problem by using a suitable shell command (often 'ulimit')
150
to raise the stack size limit before you run Emacs.
151

152
Patches to raise the stack size limit automatically in 'main'
153
(src/emacs.c) on various systems would be greatly appreciated.
Dave Love's avatar
Dave Love committed
154

155
** Error message 'Symbol’s value as variable is void: x', followed by
156
a segmentation fault and core dump.
157

158 159
This has been tracked to a bug in tar!  People report that tar erroneously
added a line like this at the beginning of files of Lisp code:
160

161
   x FILENAME, N bytes, B tape blocks
162

163 164
If your tar has this problem, install GNU tar--if you can manage to
untar it :-).
165

166
** Emacs can crash when displaying PNG images with transparency.
167

168
This is due to a bug introduced in ImageMagick 6.8.2-3.  The bug should
169
be fixed in ImageMagick 6.8.3-10.  See <URL:https://debbugs.gnu.org/13867>.
170

171 172 173 174 175
** Crashes when displaying GIF images in Emacs built with version
libungif-4.1.0 are resolved by using version libungif-4.1.0b1.
Configure checks for the correct version, but this problem could occur
if a binary built against a shared libungif is run on a system with an
older version.
176

177
** Emacs aborts inside the function 'tparam1'.
178

179 180 181 182 183
This can happen if Emacs was built without terminfo support, but the
terminal's capabilities use format that is only supported by terminfo.
If your system has ncurses installed, this might happen if your
version of ncurses is broken; upgrading to a newer version of ncurses
and reconfiguring and rebuilding Emacs should solve this.
184

185 186 187
All modern systems support terminfo, so even if ncurses is not the
problem, you should look for a way to configure Emacs so that it uses
terminfo when built.
188

189
** Emacs crashes when using some version of the Exceed X server.
190

191 192 193
Upgrading to a newer version of Exceed has been reported to prevent
these crashes.  You should consider switching to a free X server, such
as Xming or Cygwin/X.
194

195 196 197 198 199 200 201 202 203 204 205 206
** Emacs crashes with SIGSEGV in XtInitializeWidgetClass.

It crashes on X, but runs fine when called with option "-nw".

This has been observed when Emacs is linked with GNU ld but without passing
the -z nocombreloc flag.  Emacs normally knows to pass the -z nocombreloc
flag when needed, so if you come across a situation where the flag is
necessary but missing, please report it via M-x report-emacs-bug.

On platforms such as Solaris, you can also work around this problem by
configuring your compiler to use the native linker instead of GNU ld.

207
** When Emacs is compiled with Gtk+, closing a display kills Emacs.
208

209
There is a long-standing bug in GTK that prevents it from recovering
210
from disconnects: https://gitlab.gnome.org/GNOME/gtk/issues/221
211

212 213 214 215
Thus, for instance, when Emacs is run as a server on a text terminal,
and an X frame is created, and the X server for that frame crashes or
exits unexpectedly, Emacs must exit to prevent a GTK error that would
result in an endless loop.
216

217 218
If you need Emacs to be able to recover from closing displays, compile
it with the Lucid toolkit instead of GTK.
219

220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
** Emacs compiled with GTK+ 3 crashes when run under some X servers.
This happens when the X server does not provide certain display
features that the underlying GTK+ 3 toolkit assumes.  For example, this
issue has been seen with remote X servers like X2Go.  The symptoms
are an Emacs crash, possibly triggered by the mouse entering the Emacs
window, or an attempt to resize the Emacs window.  The crash backtrace
contains a call to XQueryPointer.

This issue was fixed in the GTK+ 3 toolkit in commit 4b1c0256 in February 2018.

If your GTK+ 3 is still affected, you can avoid the issue by recompiling
Emacs with a different X toolkit, eg --with-toolkit=gtk2.

References:
https://gitlab.gnome.org/GNOME/gtk/commit/4b1c02560f0d8097bf5a11932e52fb72f3e9e94b
https://debbugs.gnu.org/24280
https://bugs.debian.org/901038
https://bugzilla.redhat.com/1483942
https://access.redhat.com/solutions/3410101

240 241 242 243 244 245 246 247
** Emacs compiled with GTK crashes at startup due to X protocol error.

This is known to happen on elementary OS GNU/Linux systems.

The error message is:

  X protocol error: BadMatch (invalid parameter attributes) on protocol request 140
  When compiled with GTK, Emacs cannot recover from X disconnects.
248
  This is a GTK bug: https://gitlab.gnome.org/GNOME/gtk/issues/221
249 250 251 252 253 254 255 256 257 258 259 260 261
  For details, see etc/PROBLEMS.
  Fatal error 6: Aborted

followed by a C backtrace.  (Sometimes the offending protocol request
number is 139.)

The relevant bug report is here:

  https://bugs.launchpad.net/elementaryos/+bug/1355274

A workaround is to set XLIB_SKIP_ARGB_VISUALS=1 in the environment
before starting Emacs, or run Emacs as root.

262
** Emacs crashes when you try to view a file with complex characters.
263

264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290
One possible reason for this could be a bug in the libotf or the
libm17n-flt/m17n-db libraries Emacs uses for displaying complex
scripts.  Make sure you have the latest versions of these libraries
installed.  If the problem still persists with the latest released
versions of these libraries, you can try building these libraries from
their CVS repository:

  cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/m17n co libotf
  cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/m17n co m17n-db
  cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/m17n co m17n-lib

One known problem that causes such crashes is with using Noto Serif
Kannada fonts.  To work around that, force Emacs not to select these
fonts, by adding the following to your ~/.emacs init file:

  (push "Noto Serif Kannada" face-ignored-fonts)

You can try this interactively in a running Emacs session like this:

  M-: (push "Noto Serif Kannada" face-ignored-fonts) RET

Another set of problems is caused by an incompatible libotf library.
In this case, displaying the etc/HELLO file (as shown by C-h h)
triggers the following message to be shown in the terminal from which
you launched Emacs:

  symbol lookup error: /usr/bin/emacs: undefined symbol: OTF_open
291 292 293 294 295 296 297 298 299 300 301 302 303 304

This problem occurs because unfortunately there are two libraries
called "libotf".  One is the library for handling OpenType fonts,
http://www.m17n.org/libotf/, which is the one that Emacs expects.
The other is a library for Open Trace Format, and is used by some
versions of the MPI message passing interface for parallel
programming.

For example, on RHEL6 GNU/Linux, the OpenMPI rpm provides a version
of "libotf.so" in /usr/lib/openmpi/lib.  This directory is not
normally in the ld search path, but if you want to use OpenMPI,
you must issue the command "module load openmpi".  This adds
/usr/lib/openmpi/lib to LD_LIBRARY_PATH.  If you then start Emacs from
the same shell, you will encounter this crash.
305
Ref: <URL:https://bugzilla.redhat.com/show_bug.cgi?id=844776>
306 307 308 309 310 311 312 313

There is no good solution to this problem if you need to use both
OpenMPI and Emacs with libotf support.  The best you can do is use a
wrapper shell script (or function) "emacs" that removes the offending
element from LD_LIBRARY_PATH before starting emacs proper.
Or you could recompile Emacs with an -Wl,-rpath option that
gives the location of the correct libotf.

314
* General runtime problems
315

316
** Lisp problems
317

318
*** Changes made to .el files do not take effect.
319

320 321 322 323
You may have forgotten to recompile them into .elc files.
Then the old .elc files will be loaded, and your changes
will not be seen.  To fix this, do M-x byte-recompile-directory
and specify the directory that contains the Lisp files.
324

325
Emacs prints a warning when loading a .elc file which is older
326
than the corresponding .el file.
327

328
Alternatively, if you set the option 'load-prefer-newer' non-nil,
329 330 331
Emacs will load whichever version of a file is the newest.

*** Watch out for the EMACSLOADPATH environment variable
332

333
EMACSLOADPATH overrides which directories the function "load" will search.
334

335 336
If you observe strange problems, check for this variable in your
environment.
Dave Love's avatar
Dave Love committed
337

338
*** Using epop3.el package causes Emacs to signal an error.
Dave Love's avatar
Dave Love committed
339

340
The error message might be something like this:
341

342
  "Lisp nesting exceeds max-lisp-eval-depth"
343

344 345
This happens because epop3 redefines the function gethash, which is a
built-in primitive beginning with Emacs 21.1.  We don't have a patch
Ivan Shmakov's avatar
Ivan Shmakov committed
346
for epop3 to fix it, but perhaps a newer version of epop3 corrects that.
347

348
*** Buffers from 'with-output-to-temp-buffer' get set up in Help mode.
349

350 351 352
Changes in Emacs 20.4 to the hooks used by that function cause
problems for some packages, specifically BBDB.  See the function's
documentation for the hooks involved.  BBDB 2.00.06 fixes the problem.
353

354
*** The Hyperbole package causes *Help* buffers not to be displayed in
355 356
Help mode due to setting 'temp-buffer-show-hook' rather than using
'add-hook'.  Using '(add-hook 'temp-buffer-show-hook 'help-mode-finish)'
357
after loading Hyperbole should fix this.
358

359
** Keyboard problems
360

361 362 363 364
*** Unable to enter the M-| key on some German keyboards.
Some users have reported that M-| suffers from "keyboard ghosting".
This can't be fixed by Emacs, as the keypress never gets passed to it
at all (as can be verified using "xev").  You can work around this by
365
typing 'ESC |' instead.
366

367
*** "Compose Character" key does strange things when used as a Meta key.
368

369 370 371 372 373 374
If you define one key to serve as both Meta and Compose Character, you
will get strange results.  In previous Emacs versions, this "worked"
in that the key acted as Meta--that's because the older Emacs versions
did not try to support Compose Character.  Now Emacs tries to do
character composition in the standard X way.  This means that you
must pick one meaning or the other for any given key.
375

376 377
You can use both functions (Meta, and Compose Character) if you assign
them to two different keys.
378

379
*** C-z just refreshes the screen instead of suspending Emacs.
380

381 382
You are probably using a shell that doesn't support job control, even
though the system itself is capable of it.  Either use a different shell,
383
or set the variable 'cannot-suspend' to a non-nil value.
384

385
** Mailers and other helper programs
386

387
*** movemail compiled with POP support can't connect to the POP server.
388

389 390 391 392 393 394 395 396 397 398 399
This problem can occur if you do not configure --with-mailutils,
and don't have GNU Mailutils installed.  Then Emacs uses its own
version of movemail, which doesn't support secure POP connections.
To solve this, install GNU Mailutils.

Also, make sure that the 'pop' entry in /etc/services, or in the
services NIS map if your machine uses NIS, has the same port number as
the entry on the POP server.  A common error is for the POP server to
be listening on port 110, the assigned port for the POP3 protocol,
while the client is trying to connect on port 109, the assigned port
for the old POP protocol.
400

401
*** RMAIL gets error getting new mail.
402

403
RMAIL gets new mail from /usr/spool/mail/$USER using a program
404
called 'movemail'.  This program interlocks with /bin/mail using
405
the protocol defined by /bin/mail.
406

407
There are two different protocols in general use.  One of them uses
408 409
the 'flock' system call.  The other involves creating a lock file;
'movemail' must be able to write in /usr/spool/mail in order to do
410
this.  You control which one is used by defining, or not defining,
411
the macro MAIL_USE_FLOCK in config.h.
412 413
IF YOU DON'T USE THE FORM OF INTERLOCKING THAT IS NORMAL ON YOUR
SYSTEM, YOU CAN LOSE MAIL!
414

415 416
If your system uses the lock file protocol, and fascist restrictions
prevent ordinary users from writing the lock files in /usr/spool/mail,
417 418
you may need to make 'movemail' setgid to a suitable group such as
'mail'.  To do this,  use the following commands (as root) after doing the
419
make install.
420

421 422
        chgrp mail movemail
        chmod 2755 movemail
423

424 425 426 427 428 429
Installation normally copies movemail from the build directory to an
installation directory which is usually under /usr/local/lib.  The
installed copy of movemail is usually in the directory
/usr/local/lib/emacs/VERSION/TARGET.  You must change the group and
mode of the installed copy; changing the group and mode of the build
directory copy is ineffective.
430

431
*** rcs2log gives you the awk error message "too many fields".
432

433 434
This is due to an arbitrary limit in certain versions of awk.
The solution is to use gawk (GNU awk).
435

436
** Problems with hostname resolution
437

438
*** Emacs does not know your host's fully-qualified domain name.
439

440 441 442
For example, (system-name) returns some variation on
"localhost.localdomain", rather the name you were expecting.

443
You need to configure your machine with a fully qualified domain name,
444 445
(i.e., a name with at least one "."), either in /etc/hostname
or wherever your system calls for specifying this.
446

447 448
If you cannot fix the configuration, you can set the Lisp variable
mail-host-address to the value you want.
449

450
** NFS
451

452 453
*** Emacs says it has saved a file, but the file does not actually
appear on disk.
454

455 456 457 458
This can happen on certain systems when you are using NFS, if the
remote disk is full.  It is due to a bug in NFS (or certain NFS
implementations), and there is apparently nothing Emacs can do to
detect the problem.  Emacs checks the failure codes of all the system
459
calls involved in writing a file, including 'close'; but in the case
460
where the problem occurs, none of those system calls fails.
461

462
** PSGML conflicts with sgml-mode.
463

464 465 466 467 468 469 470
PSGML package uses the same names of some variables (like keymap)
as built-in sgml-mode.el because it was created as a replacement
of that package.  The conflict will be shown if you load
sgml-mode.el before psgml.el.  E.g. this could happen if you edit
HTML page and then start to work with SGML or XML file.  html-mode
(from sgml-mode.el) is used for HTML file and loading of psgml.el
(for sgml-mode or xml-mode) will cause an error.
471

472 473 474 475 476 477 478 479 480 481 482 483 484 485
** PCL-CVS

*** Lines are not updated or new lines are added in the buffer upon commit.

When committing files located higher in the hierarchy than the examined
directory, some versions of the CVS program return an ambiguous message
from which PCL-CVS cannot extract the full location of the committed
files.  As a result, the corresponding lines in the PCL-CVS buffer are
not updated with the new revision of these files, and new lines are
added to the top-level directory.

This can happen with CVS versions 1.12.8 and 1.12.9.  Upgrade to CVS
1.12.10 or newer to fix this problem.

486
** Miscellaneous problems
487

488 489 490 491 492 493
*** Editing files with very long lines is slow.

For example, simply moving through a file that contains hundreds of
thousands of characters per line is slow, and consumes a lot of CPU.
This is a known limitation of Emacs with no solution at this time.

494 495
*** Emacs uses 100% of CPU time

496 497 498 499
This was a known problem with some old versions of the Semantic package.
The solution was to upgrade Semantic to version 2.0pre4 (distributed
with CEDET 1.0pre4) or later.  Note that Emacs includes Semantic since
23.2, and this issue does not apply to the included version.
500

501 502 503 504 505 506 507 508 509 510 511 512 513 514 515
*** Display artifacts on GUI frames on X-based systems.

This is known to be caused by using double-buffering (which is enabled
by default in Emacs 26 and later).  The artifacts typically appear
after commands that cause Emacs to scroll the display.

You can disable double-buffering by evaluating the following form:

  (modify-all-frames-parameters '((inhibit-double-buffering . t)))

To make this permanent, add it to your ~/.emacs init file.

Note that disabling double-buffering will cause flickering of the
display in some situations.

516
*** Self-documentation messages are garbled.
Jason Rumney's avatar
Jason Rumney committed
517

518
This means that the file 'etc/DOC' doesn't properly correspond
519 520
with the Emacs executable.  Redumping Emacs and then installing the
corresponding pair of files should fix the problem.
521

522
*** Programs running under terminal emulator do not recognize 'emacs'
523
terminal type.
524

525 526
The cause of this is a shell startup file that sets the TERMCAP
environment variable.  The terminal emulator uses that variable to
527
provide the information on the special terminal type that Emacs emulates.
528

529 530 531
Rewrite your shell startup file so that it does not change TERMCAP
in such a case.  You could use the following conditional which sets
it only if it is undefined.
532

533
    if ( ! ${?TERMCAP} ) setenv TERMCAP ~/my-termcap-file
534

535 536
Or you could set TERMCAP only when you set TERM--which should not
happen in a non-login shell.
537

538
*** In Shell mode, you get a ^M at the end of every line.
539

540
This happens to people who use tcsh, because it is trying to be too
541
smart.  It sees that the Shell uses terminal type 'unknown' and turns
542 543
on the flag to output ^M at the end of each line.  You can fix the
problem by adding this to your .cshrc file:
544

545 546 547
    if ($?INSIDE_EMACS && $?tcsh)
        unset edit
        stty -icrnl -onlcr -echo susp ^Z
548
    endif
549

550 551 552 553 554 555 556 557 558 559 560
*** In Shell buffers using ksh, resizing a window inserts random characters.

The characters come from the PS2 prompt, but they are not followed by
a newline, which messes up the next command you type.  This strange
effect is caused by Emacs 25 and later telling the shell that its
screen size changed.

To work around the problem, customize the option
'window-adjust-process-window-size-function' to "Do not adjust process
window sizes" (Lisp value 'ignore').

561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577
*** In Inferior Python mode, input is echoed and native completion doesn't work.
<https://debbugs.gnu.org/cgi/bugreport.cgi?bug=25753>

This happens when python uses a libedit based readline module, which
is the default on macOS.  This can be worked around by installing a
GNU readline based module instead, for example, using setuptools

    sudo easy_install gnureadline

And then rename the system's readline so that it won't be loaded:

    cd /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload
    mv readline.so readline.so.bak

See <https://pypi.python.org/pypi/gnureadline> for more details on
installation.

578
*** Visiting files in some auto-mounted directories causes Emacs to print
579
'Error reading dir-locals: (file-error "Read error" "is a directory" ...'
580 581 582 583

This can happen if the auto-mounter mistakenly reports that
.dir-locals.el exists and is a directory.  There is nothing Emacs can
do about this, but you can avoid the issue by adding a suitable entry
584
to the variable 'locate-dominating-stop-dir-regexp'.  For example, if
585 586 587
the problem relates to "/smb/.dir-locals.el", set that variable
to a new value where you replace "net\\|afs" with "net\\|afs\\|smb".
(The default value already matches common auto-mount prefixes.)
588
See https://lists.gnu.org/r/help-gnu-emacs/2015-02/msg00461.html .
589

590
*** Attempting to visit remote files via ange-ftp fails.
591

592
If the error message is "ange-ftp-file-modtime: Specified time is not
593
representable", then this could happen when 'lukemftp' is used as the
594
ftp client.  This was reported to happen on Debian GNU/Linux, kernel
595
version 2.4.3, with 'lukemftp' 1.5-5, but might happen on other
596 597
systems as well.  To avoid this problem, switch to using the standard
ftp client.  On a Debian system, type
598

599
  update-alternatives --config ftp
600

601
and then choose /usr/bin/netkit-ftp.
602

603
*** Dired is very slow.
604

605
This could happen if getting a file system's status takes a long
606 607
time.  Possible reasons for this include:

608
  - ClearCase mounted filesystems (VOBs) that sometimes make 'df'
609 610 611 612
    response time extremely slow (dozens of seconds);

  - slow automounters on some old versions of Unix;

613 614
To work around the problem, you could use Git or some other
free-software program, instead of ClearCase.
615

616
*** ps-print commands fail to find prologue files ps-prin*.ps.
617 618 619 620 621 622 623

This can happen if you use an old version of X-Symbol package: it
defines compatibility functions which trick ps-print into thinking it
runs in XEmacs, and look for the prologue files in a wrong directory.

The solution is to upgrade X-Symbol to a later version.

624
*** On systems with shared libraries you might encounter run-time errors
625 626 627 628 629
from the dynamic linker telling you that it is unable to find some
shared libraries, for instance those for Xaw3d or image support.
These errors mean Emacs has been linked with a library whose shared
library is not in the default search path of the dynamic linker.

630 631 632
Similar problems could prevent Emacs from building, since the build
process invokes Emacs several times.

633 634 635 636 637 638 639 640 641 642
On many systems, it is possible to set LD_LIBRARY_PATH in your
environment to specify additional directories where shared libraries
can be found.

Other systems allow to set LD_RUN_PATH in a similar way, but before
Emacs is linked.  With LD_RUN_PATH set, the linker will include a
specified run-time search path in the executable.

Please refer to the documentation of your dynamic linker for details.

643
*** When you run Ispell from Emacs, it reports a "misalignment" error.
644

645 646 647 648
This can happen if you compiled the Ispell program to use ASCII
characters only and then try to use it from Emacs with non-ASCII
characters, like Latin-1.  The solution is to recompile Ispell with
support for 8-bit characters.
649

650 651
To see whether your Ispell program supports 8-bit characters, type
this at your shell's prompt:
652

653
     ispell -vv
654

655 656 657
and look in the output for the string "NO8BIT".  If Ispell says
"!NO8BIT (8BIT)", your speller supports 8-bit characters; otherwise it
does not.
658

659 660 661
To rebuild Ispell with 8-bit character support, edit the local.h file
in the Ispell distribution and make sure it does _not_ define NO8BIT.
Then rebuild the speller.
662

663 664
Another possible cause for "misalignment" error messages is that the
version of Ispell installed on your machine is old.  Upgrade.
665

666 667 668 669 670
Yet another possibility is that you are trying to spell-check a word
in a language that doesn't fit the dictionary you choose for use by
Ispell.  (Ispell can only spell-check one language at a time, because
it uses a single dictionary.)  Make sure that the text you are
spelling and the dictionary used by Ispell conform to each other.
671

672 673
If your spell-checking program is Aspell, it has been reported that if
you have a personal configuration file (normally ~/.aspell.conf), it
674
can cause this error.  Remove that file, execute 'ispell-kill-ispell'
675
in Emacs, and then try spell-checking again.
676

677
*** TLS problems, e.g., Gnus hangs when fetching via imaps
678
https://debbugs.gnu.org/24247
679 680 681 682 683 684

gnutls-cli 3.5.3 (2016-08-09) does not generate a "- Handshake was
completed" message that tls.el relies upon, causing affected Emacs
functions to hang.  To work around the problem, use older or newer
versions of gnutls-cli, or use Emacs's built-in gnutls support.

685
* Runtime problems related to font handling
686

687 688 689 690 691 692 693
** Characters are displayed as empty boxes or with wrong font under X.

*** This can occur when two different versions of FontConfig are used.
For example, XFree86 4.3.0 has one version and Gnome usually comes
with a newer version.  Emacs compiled with Gtk+ will then use the
newer version.  In most cases the problem can be temporarily fixed by
stopping the application that has the error (it can be Emacs or any
Ivan Shmakov's avatar
Ivan Shmakov committed
694
other application), removing ~/.fonts.cache-1, and then starting the
695 696 697 698 699 700 701 702 703 704 705 706
application again.  If removing ~/.fonts.cache-1 and restarting
doesn't help, the application with problem must be recompiled with the
same version of FontConfig as the rest of the system uses.  For KDE,
it is sufficient to recompile Qt.

*** Some fonts have a missing glyph and no default character.  This is
known to occur for character number 160 (no-break space) in some
fonts, such as Lucida but Emacs sets the display table for the unibyte
and Latin-1 version of this character to display a space.

*** Some of the fonts called for in your fontset may not exist on your
X server.
707

708
Each X font covers just a fraction of the characters that Emacs
709
supports.  To display the whole range of Emacs characters requires
710 711
many different fonts, collected into a fontset.  You can remedy the
problem by installing additional fonts.
712

713
The intlfonts distribution includes a full spectrum of fonts that can
714
display all the characters Emacs supports.  The etl-unicode collection
715 716 717 718
of fonts (available from
<https://ftp.nluug.nl/windowing/X/contrib/fonts/>) includes fonts that
can display many Unicode characters; they can also be used by ps-print
and ps-mule to print Unicode characters.
719

720
** Under X, some characters appear improperly aligned in their lines.
721

722
You may have bad fonts.
723 724 725 726 727 728 729 730 731

** Under X, an unexpected monospace font is used as the default font.

When compiled with XFT, Emacs tries to use a default font named
"monospace".  This is a "virtual font", which the operating system
(Fontconfig) redirects to a suitable font such as DejaVu Sans Mono.
On some systems, there exists a font that is actually named Monospace,
which takes over the virtual font.  This is considered an operating
system bug; see
732

733
https://lists.gnu.org/r/emacs-devel/2008-10/msg00696.html
734

735 736 737 738 739 740 741 742 743 744 745
If you encounter this problem, set the default font to a specific font
in your .Xresources or initialization file.  For instance, you can put
the following in your .Xresources:

Emacs.font: DejaVu Sans Mono 12

** Certain fonts make each line take one pixel more than it should.

This is because these fonts contain characters a little taller than
the font's nominal height.  Emacs needs to make sure that lines do not
overlap.
746

747
** Font Lock displays portions of the buffer in incorrect faces.
748

749 750
By far the most frequent cause of this is a parenthesis '(' or a brace
'{' in column zero.  Font Lock assumes that such a paren is outside of
751 752 753 754 755 756 757 758
any comment or string.  This is of course not true in general, but the
vast majority of well-formatted program source files don't have such
parens, and therefore this assumption is used to allow optimizations
in Font Lock's syntactical analysis.  These optimizations avoid some
pathological cases where jit-lock, the Just-in-Time fontification
introduced with Emacs 21.1, could significantly slow down scrolling
through the buffer, especially scrolling backwards, and also jumping
to the end of a very large buffer.
759

760
Beginning with version 22.1, a parenthesis or a brace in column zero
761 762 763
is highlighted in bold-red face if it is inside a string or a comment,
to indicate that it could interfere with Font Lock (and also with
indentation) and should be moved or escaped with a backslash.
764

765 766 767
If you don't use large buffers, or have a very fast machine which
makes the delays insignificant, you can avoid the incorrect
fontification by setting the variable
768
'font-lock-beginning-of-syntax-function' to a nil value.  (This must
769
be done _after_ turning on Font Lock.)
770

771 772
Another alternative is to avoid a paren in column zero.  For example,
in a Lisp string you could precede the paren with a backslash.
773

774
** Emacs pauses for several seconds when changing the default font.
775

776 777 778 779
This has been reported for fvwm 2.2.5 and the window manager of KDE
2.1.  The reason for the pause is Xt waiting for a ConfigureNotify
event from the window manager, which the window manager doesn't send.
Xt stops waiting after a default timeout of usually 5 seconds.
780

781
A workaround for this is to add something like
782

783
emacs.waitForWM: false
784

785
to your X resources.  Alternatively, add '(wait-for-wm . nil)' to a
786
frame's parameter list, like this:
787

788
   (modify-frame-parameters nil '((wait-for-wm . nil)))
789

790
(this should go into your '.emacs' file).
791

792
** Underlines appear at the wrong position.
793

794
This is caused by fonts having a wrong UNDERLINE_POSITION property.
795 796
To avoid this problem (seen in some very old X releases and font packages),
set x-use-underline-position-properties to nil.
797

798
To see what is the value of UNDERLINE_POSITION defined by the font,
799
type 'xlsfonts -lll FONT' and look at the font's UNDERLINE_POSITION property.
Dave Love's avatar
Dave Love committed
800

801
** When using Exceed, fonts sometimes appear too tall.
802

803 804 805 806 807
When the display is set to an Exceed X-server and fonts are specified
(either explicitly with the -fn option or implicitly with X resources)
then the fonts may appear "too tall".  The actual character sizes are
correct but there is too much vertical spacing between rows,  which
gives the appearance of "double spacing".
808

809 810
To prevent this, turn off the Exceed's "automatic font substitution"
feature (in the font part of the configuration window).
811

812 813
** Subscript/superscript text in TeX is hard to read.

814
If 'tex-fontify-script' is non-nil, tex-mode displays
815 816 817 818 819 820 821 822 823
subscript/superscript text in the faces subscript/superscript, which
are smaller than the normal font and lowered/raised.  With some fonts,
nested superscripts (say) can be hard to read.  Switching to a
different font, or changing your antialiasing setting (on an LCD
screen), can both make the problem disappear.  Alternatively, customize
the following variables: tex-font-script-display (how much to
lower/raise); tex-suscript-height-ratio (how much smaller than
normal); tex-suscript-height-minimum (minimum height).

824 825 826 827 828 829 830 831 832 833 834 835 836 837
** Screen refresh is slow when there are special characters for which no suitable font is available

If the display is too slow in refreshing when you scroll to a new
region, or when you edit the buffer, it might be due to the fact that
some characters cannot be displayed in the default font, and Emacs is
spending too much time in looking for a suitable font to display them.

You can suspect this if you have several characters that are displayed
as small rectangles containing a hexadecimal code inside.

The solution is to install the appropriate fonts on your machine. For
instance if you are editing a text with a lot of math symbols, then
installing a font like 'Symbola' should solve this problem.

838 839 840 841
Another reason for slow display is reportedly the nerd-fonts
installation, even when Symbola is installed as well.  Uninstalling
nerd-fonts was reported to solve the problem in that case.

842
** Emacs running on GNU/Linux system with the m17n library Ver.1.7.1 or the
843
earlier version has a problem with rendering Bengali script.
844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871

The problem can be fixed by installing the newer version of the m17n
library (if any), or by following this procedure:

1. Locate the file BENG-OTF.flt installed on your system as part of the
m17n library.  Usually it is under the directory /usr/share/m17n.

2. Apply the following patch to BENG-OTF.flt

------------------------------------------------------------
diff --git a/FLT/BENG-OTF.flt b/FLT/BENG-OTF.flt
index 45cc554..0cc5e76 100644
--- a/FLT/BENG-OTF.flt
+++ b/FLT/BENG-OTF.flt
@@ -232,7 +232,7 @@
  (lang-forms
   (cond
    ("(.H)J" (1 :otf=beng=half+))
-   (".H" :otf=beng=blwf,half,vatu+)
+   (".+H" :otf=beng=blwf,half,vatu+)
    ("." =)))

  (post
------------------------------------------------------------

If you can't modify that file directly, copy it to the directory
~/.m17n.d/ (create it if it doesn't exist), and apply the patch.

872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901
** Emacs running on GNU/Linux system with the m17n library Ver.1.7.1 or the
earlier version has a problem with rendering Lao script with OpenType font.

The problem can be fixed by installing the newer version of the m17n
library (if any), or by following this procedure:

1. Locate the file LAOO-OTF.flt installed on your system as part of the
m17n library.  Usually it is under the directory /usr/share/m17n.

2. Apply the following patch to LAOO-OTF.flt

------------------------------------------------------------
diff --git a/FLT/LAOO-OTF.flt b/FLT/LAOO-OTF.flt
index 5504171..431adf8 100644
--- a/FLT/LAOO-OTF.flt
+++ b/FLT/LAOO-OTF.flt
@@ -3,7 +3,7 @@
 ;; See the end for copying conditions.

 (font layouter laoo-otf nil
-      (font (nil phetsarath\ ot unicode-bmp)))
+      (font (nil nil unicode-bmp :otf=lao\ )))

 ;;; <li> LAOO-OTF.flt

------------------------------------------------------------

If you can't modify that file directly, copy it to the directory
~/.m17n.d/ (create it if it doesn't exist), and apply the patch.

902
* Internationalization problems
903

904 905 906 907 908
** M-{ does not work on a Spanish PC keyboard.

Many Spanish keyboards seem to ignore that combination.  Emacs can't
do anything about it.

909 910 911
** International characters aren't displayed under X.

*** Missing X fonts
912

913 914 915 916 917 918 919 920 921
XFree86 4 contains many fonts in iso10646-1 encoding which have
minimal character repertoires (whereas the encoding part of the font
name is meant to be a reasonable indication of the repertoire
according to the XLFD spec).  Emacs may choose one of these to display
characters from the mule-unicode charsets and then typically won't be
able to find the glyphs to display many characters.  (Check with C-u
C-x = .)  To avoid this, you may need to use a fontset which sets the
font for the mule-unicode sets explicitly.  E.g. to use GNU unifont,
include in the fontset spec:
922

923 924 925
mule-unicode-2500-33ff:-gnu-unifont-*-iso10646-1,\
mule-unicode-e000-ffff:-gnu-unifont-*-iso10646-1,\
mule-unicode-0100-24ff:-gnu-unifont-*-iso10646-1
926

927
** The UTF-8/16/7 coding systems don't encode CJK (Far Eastern) characters.
928

929 930 931 932 933 934 935 936 937 938
Emacs directly supports the Unicode BMP whose code points are in the
ranges 0000-33ff and e000-ffff, and indirectly supports the parts of
CJK characters belonging to these legacy charsets:

    GB2312, Big5, JISX0208, JISX0212, JISX0213-1, JISX0213-2, KSC5601

The latter support is done in Utf-Translate-Cjk mode (turned on by
default).   Which Unicode CJK characters are decoded into which Emacs
charset is decided by the current language environment.  For instance,
in Chinese-GB, most of them are decoded into chinese-gb2312.
Dave Love's avatar
Dave Love committed
939

940 941 942 943 944
If you read UTF-8 data with code points outside these ranges, the
characters appear in the buffer as raw bytes of the original UTF-8
(composed into a single quasi-character) and they will be written back
correctly as UTF-8, assuming you don't break the composed sequences.
If you read such characters from UTF-16 or UTF-7 data, they are
945
substituted with the Unicode 'replacement character', and you lose
946
information.
Dave Love's avatar
Dave Love committed
947

948
** Accented ISO-8859-1 characters are displayed as | or _.
Dave Love's avatar
#  
Dave Love committed
949

950 951 952 953
Try other font set sizes (S-mouse-1).  If the problem persists with
other sizes as well, your text is corrupted, probably through software
that is not 8-bit clean.  If the problem goes away with another font
size, it's probably because some fonts pretend to be ISO-8859-1 fonts
954
when they are really ASCII fonts.  In particular the schumacher-clean
955
fonts have this bug in some versions of X.
Dave Love's avatar
#  
Dave Love committed
956

957
To see what glyphs are included in a font, use 'xfd', like this:
Dave Love's avatar
#  
Dave Love committed
958

959
  xfd -fn -schumacher-clean-medium-r-normal--12-120-75-75-c-60-iso8859-1
Dave Love's avatar
#  
Dave Love committed
960

961
If this shows only ASCII glyphs, the font is indeed the source of the problem.
Dave Love's avatar
#  
Dave Love committed
962

963
The solution is to remove the corresponding lines from the appropriate
964 965
'fonts.alias' file, then run 'mkfontdir' in that directory, and then run
'xset fp rehash'.
966

967
** The 'oc-unicode' package doesn't work with Emacs 21.
Dave Love's avatar
#  
Dave Love committed
968

969 970
This package tries to define more private charsets than there are free
slots now.  The current built-in Unicode support is actually more
971
flexible.  (Use option 'utf-translate-cjk-mode' if you need CJK
972 973
support.)  Files encoded as emacs-mule using oc-unicode aren't
generally read correctly by Emacs 21.
Dave Love's avatar
#  
Dave Love committed
974

975
* X runtime problems
976

977
** X keyboard problems
978

979
*** You "lose characters" after typing Compose Character key.
Dave Love's avatar
#  
Dave Love committed
980

981
This is because the Compose Character key is defined as the keysym
982
Multi_key, and Emacs (seeing that) does the proper X
983 984
character-composition processing.  If you don't want your Compose key
to do that, you can redefine it with xmodmap.
Dave Love's avatar
#  
Dave Love committed
985

986
For example, here's one way to turn it into a Meta key:
987

988
    xmodmap -e "keysym Multi_key = Meta_L"
Dave Love's avatar
#  
Dave Love committed
989

990 991 992
If all users at your site of a particular keyboard prefer Meta to
Compose, you can make the remapping happen automatically by adding the
xmodmap command to the xdm setup script for that display.
Dave Love's avatar
#  
Dave Love committed
993

Ivan Shmakov's avatar
Ivan Shmakov committed
994
*** Using X Window System, control-shift-leftbutton makes Emacs hang.
Dave Love's avatar
#  
Dave Love committed
995

996
Use the shell command 'xset bc' to make the old X Menu package work.
Dave Love's avatar
#  
Dave Love committed
997

998
*** C-SPC fails to work on Fedora GNU/Linux (or with fcitx input method).
999

1000
Fedora Core 4 steals the C-SPC key by default for the 'iiimx' program
1001
which is the input method for some languages.  It blocks Emacs users
1002
from using the C-SPC key for 'set-mark-command'.
1003

1004 1005
One solutions is to remove the '<Ctrl>space' from the 'Iiimx' file
which can be found in the '/usr/lib/X11/app-defaults' directory.
1006 1007
However, that requires root access.

1008
Another is to specify 'Emacs*useXIM: false' in your X resources.
1009

1010
Another is to build Emacs with the '--without-xim' configure option.
1011

1012 1013 1014 1015
The same problem happens on any other system if you are using fcitx
(Chinese input method) which by default use C-SPC for toggling.  If
you want to use fcitx with Emacs, you have two choices.  Toggle fcitx
by another key (e.g. C-\) by modifying ~/.fcitx/config, or be
1016
accustomed to use C-@ for 'set-mark-command'.
1017

1018 1019 1020
*** Link-time optimization with clang doesn't work on Fedora 20.

As of May 2014, Fedora 20 has broken LLVMgold.so plugin support in clang
1021 1022 1023
(tested with clang-3.4-6.fc20) - 'clang --print-file-name=LLVMgold.so'
prints 'LLVMgold.so' instead of full path to plugin shared library, and
'clang -flto' is unable to find the plugin with the following error:
1024 1025 1026 1027 1028 1029 1030 1031

/bin/ld: error: /usr/bin/../lib/LLVMgold.so: could not load plugin library:
/usr/bin/../lib/LLVMgold.so: cannot open shared object file: No such file
or directory

The only way to avoid this is to build your own clang from source code
repositories, as described at http://clang.llvm.org/get_started.html.

1032
*** M-SPC seems to be ignored as input.
Dave Love's avatar
#  
Dave Love committed
1033

1034 1035
See if your X server is set up to use this as a command
for character composition.
Dave Love's avatar
#  
Dave Love committed
1036

1037
*** The S-C-t key combination doesn't get passed to Emacs on X.
Dave Love's avatar
#  
Dave Love committed
1038

1039 1040
This happens because some X configurations assign the Ctrl-Shift-t
combination the same meaning as the Multi_key.  The offending
1041
definition is in the file '...lib/X11/locale/iso8859-1/Compose'; there
1042 1043
might be other similar combinations which are grabbed by X for similar
purposes.
Dave Love's avatar
#  
Dave Love committed
1044

1045
We think that this can be countermanded with the 'xmodmap' utility, if
1046
you want to be able to bind one of these key sequences within Emacs.
Dave Love's avatar
#  
Dave Love committed
1047

1048
*** Under X, C-v and/or other keys don't work.
Dave Love's avatar
#  
Dave Love committed
1049

1050 1051
These may have been intercepted by your window manager.
See the WM's documentation for how to change this.
Dave Love's avatar
#  
Dave Love committed
1052

1053
*** Clicking C-mouse-2 in the scroll bar doesn't split the window.
Dave Love's avatar
#  
Dave Love committed
1054

1055 1056 1057
This currently doesn't work with scroll-bar widgets (and we don't know
a good way of implementing it with widgets).  If Emacs is configured
--without-toolkit-scroll-bars, C-mouse-2 on the scroll bar does work.
Dave Love's avatar
#  
Dave Love committed
1058

1059 1060
*** Inability to send an Alt-modified key, when Emacs is communicating
directly with an X server.
Dave Love's avatar
#  
Dave Love committed
1061

1062 1063 1064 1065 1066 1067
If you have tried to bind an Alt-modified key as a command, and it
does not work to type the command, the first thing you should check is
whether the key is getting through to Emacs.  To do this, type C-h c
followed by the Alt-modified key.  C-h c should say what kind of event
it read.  If it says it read an Alt-modified key, then make sure you
have made the key binding correctly.
Dave Love's avatar
#  
Dave Love committed
1068

1069 1070
If C-h c reports an event that doesn't have the Alt modifier, it may
be because your X server has no key for the Alt modifier.  The X
1071
server that comes from MIT does not set up the Alt modifier by default.
Dave Love's avatar
#  
Dave Love committed
1072

1073
If your keyboard has keys named Alt, you can enable them as follows:
Dave Love's avatar
#  
Dave Love committed
1074

1075 1076
    xmodmap -e 'add mod2 = Alt_L'
    xmodmap -e 'add mod2 = Alt_R'
Dave Love's avatar
#  
Dave Love committed
1077

1078
If the keyboard has just one key named Alt, then only one of those
1079
commands is needed.  The modifier 'mod2' is a reasonable choice if you
1080 1081
are using an unmodified MIT version of X.  Otherwise, choose any
modifier bit not otherwise used.
Dave Love's avatar
#  
Dave Love committed
1082

1083 1084 1085 1086
If your keyboard does not have keys named Alt, you can use some other
keys.  Use the keysym command in xmodmap to turn a function key (or
some other 'spare' key) into Alt_L or into Alt_R, and then use the
commands show above to make them modifier keys.
Dave Love's avatar
#  
Dave Love committed
1087

1088 1089
Note that if you have Alt keys but no Meta keys, Emacs translates Alt
into Meta.  This is because of the great importance of Meta in Emacs.
Dave Love's avatar
#  
Dave Love committed
1090

1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103
*** Emacs hangs or crashes when a large portion of text is selected or killed.

This is caused by a bug in the clipboard management applets (it has
been observed in 'klipper' and 'clipit'), which periodically request
the X clipboard contents from applications.  After a while, Emacs may
print a message:

  Timed out waiting for property-notify event

A workaround is to not use 'klipper'/'clipit'.  Upgrading 'klipper' to
the one coming with KDE 3.3 or later might solve the problem; if it
doesn't, set 'select-active-regions' to 'only' or nil.

1104
** Window-manager and toolkit-related problems
Dave Love's avatar
#  
Dave Love committed
1105

1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120
*** Emacs built with GTK+ toolkit produces corrupted display on HiDPI screen

This can happen if you set GDK_SCALE=2 in the environment or in your
'.xinitrc' file.  (This setting is usually accompanied by
GDK_DPI_SCALE=0.5.)  Emacs can not support these settings correctly,
as it doesn't use GTK+ exclusively.  The result is that sometimes
widgets like the scroll bar are displayed incorrectly, and frames
could be displayed "cropped" to only part of the stuff that should be
displayed.

The workaround is to explicitly disable these settings when invoking
Emacs, for example (from a Posix shell prompt):

  $ GDK_SCALE=1 GDK_DPI_SCALE=1 emacs

1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137
*** Emacs built with GTK+ toolkit can unexpectedly widen frames

This resizing takes place when a frame is not wide enough to accommodate
its entire menu bar.  Typically, it occurs when switching buffers or
changing a buffer's major mode and the new mode adds entries to the menu
bar.  The frame is then widened by the window manager so that the menu
bar is fully shown.  Subsequently switching to another buffer or
changing the buffer's mode will not shrink the frame back to its
previous width.  The height of the frame remains unaltered.  Apparently,
the failure is also dependent on the chosen font.

The resizing is usually accompanied by console output like

Gtk-CRITICAL **: gtk_distribute_natural_allocation: assertion 'extra_space >= 0' failed

It's not clear whether the GTK version used has any impact on the
occurrence of the failure.  So far, the failure has been observed with
1138 1139
GTK+ versions 3.4.2, 3.14.5 and 3.18.7.  However, another 3.4.2 build
does not exhibit the bug.
1140

Paul Eggert's avatar
Paul Eggert committed
1141
Some window managers (Xfce) apparently work around this failure by
1142 1143 1144 1145 1146
cropping the menu bar.  With other windows managers, it's possible to
shrink the frame manually after the problem occurs, e.g. by dragging the
frame's border with the mouse.  However, some window managers have been
reported to refuse such attempts and snap back to the width needed to
show the full menu bar (wmii) or at least cause the screen to flicker
Paul Eggert's avatar
Paul Eggert committed
1147
during such resizing attempts (i3, IceWM).
1148

1149 1150 1151
See also https://debbugs.gnu.org/cgi/bugreport.cgi?bug=15700,
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22000,
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22898 and
1152
https://lists.gnu.org/r/emacs-devel/2016-07/msg00154.html.
1153

1154 1155 1156 1157
*** Metacity: Resizing Emacs or ALT-Tab causes X to be unresponsive.

This happens sometimes when using Metacity.  Resizing Emacs or ALT-Tab:bing
makes the system unresponsive to the mouse or the keyboard.  Killing Emacs
1158
or shifting out from X and back again usually cures it (i.e. Ctrl-Alt-F1
1159 1160 1161 1162
and then Alt-F7).  A bug for it is here:
https://bugs.launchpad.net/ubuntu/+source/metacity/+bug/231034.
Note that a permanent fix seems to be to disable "assistive technologies".

1163 1164 1165 1166 1167 1168 1169
*** Gnome: Emacs receives input directly from the keyboard, bypassing XIM.

This seems to happen when gnome-settings-daemon version 2.12 or later
is running.  If gnome-settings-daemon is not running, Emacs receives
input through XIM without any problem.  Furthermore, this seems only
to happen in *.UTF-8 locales; zh_CN.GB2312 and zh_CN.GBK locales, for
example, work fine.  A bug report has been filed in the Gnome
1170
bugzilla: https://bugzilla.gnome.org/show_bug.cgi?id=357032
1171

1172 1173 1174 1175 1176 1177 1178
*** Gnome: GPaste clipboard manager causes erratic behavior of 'yank'

The symptom is that 'kill-line' followed by 'yank' often (but not
always) doesn't insert the whitespace of the killed and yanked line.

The solution is to set the GPaste "trim items" option to OFF.

1179 1180
*** KDE: When running on KDE, colors or fonts are not as specified for Emacs,
or messed up.
Dave Love's avatar
#  
Dave Love committed
1181

1182 1183 1184
For example, you could see background you set for Emacs only in the
empty portions of the Emacs display, while characters have some other
background.
Dave Love's avatar
#  
Dave Love committed
1185

1186 1187 1188 1189 1190
This happens because KDE's defaults apply its color and font
definitions even to applications that weren't compiled for KDE.  The
solution is to uncheck the "Apply fonts and colors to non-KDE apps"
option in Preferences->Look&Feel->Style (KDE 2).  In KDE 3, this option
is in the "Colors" section, rather than "Style".
Dave Love's avatar
#  
Dave Love committed
1191

1192
Alternatively, if you do want the KDE defaults to apply to other
1193 1194
applications, but not to Emacs, you could modify the file 'Emacs.ad'
(should be in the '/usr/share/apps/kdisplay/app-defaults/' directory)
1195 1196 1197
so that it doesn't set the default background and foreground only for
Emacs.  For example, make sure the following resources are either not
present or commented out:
Dave Love's avatar
#  
Dave Love committed
1198

1199 1200 1201 1202
   Emacs.default.attributeForeground
   Emacs.default.attributeBackground
   Emacs*Foreground
   Emacs*Background
Dave Love's avatar
#  
Dave Love committed
1203

1204 1205 1206 1207
It is also reported that a bug in the gtk-engines-qt engine can cause this if
Emacs is compiled with Gtk+.
The bug is fixed in version 0.7 or newer of gtk-engines-qt.

1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229
*** KDE / Plasma 5: Emacs exhausts memory and needs to be killed

This problem occurs when large selections contain mixed line endings
(i.e. the buffer has LF line endings, but in some parts CRLF is used).
The source of the problem is currently under investigation, older
versions of Emacs up to 24.5 just hang for a few seconds and then
return with the message "Timed out waiting for property-notify event"
as described in the previous note.  As a workaround, go to the
settings dialog for the Clipboard widget and select the option "Ignore
Selection".

Note: Plasma 5 has replaced the separate klipper process from earlier
KDE versions with functionality directly integrated into plasmashell,
so even if you've previously did not use klipper this will affect you.
Also, all configuration you might have done to klipper is not used by
the new Clipboard widget / plasmoid since it uses its own settings.
You can hide the Clipboard widget by removing its entry from the
system tray settings "Extra Items", but it's not clear if the
underlying functionality in plasmashell gets fully disabled as well.
At least a restart of plasmashell is required for the clipboard
history to be cleared.

1230
*** CDE: Frames may cover dialogs they created when using CDE.
Dave Love's avatar
#  
Dave Love committed
1231

1232 1233 1234 1235
This can happen if you have "Allow Primary Windows On Top" enabled which
seems to be the default in the Common Desktop Environment.
To change, go in to "Desktop Controls" -> "Window Style Manager"
and uncheck "Allow Primary Windows On Top".
1236

1237 1238 1239 1240
*** Xaw3d : When using Xaw3d scroll bars without arrows, the very first mouse
click in a scroll bar might be ignored by the scroll bar widget.  This
is probably a bug in Xaw3d; when Xaw3d is compiled with arrows, the
problem disappears.
1241

1242 1243 1244 1245 1246 1247
*** Xaw: There are known binary incompatibilities between Xaw, Xaw3d, neXtaw,
XawM and the few other derivatives of Xaw.  So when you compile with
one of these, it may not work to dynamically link with another one.
For example, strange problems, such as Emacs exiting when you type
"C-x 1", were reported when Emacs compiled with Xaw3d and libXaw was
used with neXtaw at run time.
1248

1249 1250 1251
The solution is to rebuild Emacs with the toolkit version you actually
want to use, or set LD_PRELOAD to preload the same toolkit version you
built Emacs with.
1252

1253
*** Open Motif: Problems with file dialogs in Emacs built with Open Motif.
Dave Love's avatar
#  
Dave Love committed
1254

1255 1256 1257 1258
When Emacs 21 is built with Open Motif 2.1, it can happen that the
graphical file dialog boxes do not work properly.  The "OK", "Filter"
and "Cancel" buttons do not respond to mouse clicks.  Dragging the
file dialog window usually causes the buttons to work again.
Dave Love's avatar
#  
Dave Love committed
1259

1260
As a workaround, you can try building Emacs using Motif or LessTif instead.
Dave Love's avatar
#  
Dave Love committed
1261

1262 1263 1264
Another workaround is not to use the mouse to trigger file prompts,
but to use the keyboard.  This way, you will be prompted for a file in
the minibuffer instead of a graphical file dialog.
Dave Love's avatar
#  
Dave Love committed
1265

1266
*** LessTif: Problems in Emacs built with LessTif.
Dave Love's avatar
#  
Dave Love committed
1267

1268 1269
The problems seem to depend on the version of LessTif and the Motif
emulation for which it is set up.
Dave Love's avatar
#  
Dave Love committed
1270

1271
Only the Motif 1.2 emulation seems to be stable enough in LessTif.
Glenn Morris's avatar
Glenn Morris committed
1272
LessTif 0.92-17's Motif 1.2 emulation seems to work okay on FreeBSD.
1273 1274 1275 1276 1277
On GNU/Linux systems, lesstif-0.92.6 configured with "./configure
--enable-build-12 --enable-default-12" is reported to be the most
successful.  The binary GNU/Linux package
lesstif-devel-0.92.0-1.i386.rpm was reported to have problems with
menu placement.
Dave Love's avatar
#  
Dave Love committed
1278

1279 1280 1281
On some systems, Emacs occasionally locks up, grabbing all mouse and
keyboard events.  We don't know what causes these problems; they are
not reproducible by Emacs developers.
Dave Love's avatar
#  
Dave Love committed
1282

1283
*** Motif: The Motif version of Emacs paints the screen a solid color.
Dave Love's avatar
#  
Dave Love committed
1284

1285
This has been observed to result from the following X resource:
Dave Love's avatar
#  
Dave Love committed
1286

1287
   Emacs*default.attributeFont:	-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*
Dave Love's avatar
#  
Dave Love committed
1288

1289
That the resource has this effect indicates a bug in something, but we
1290
do not know what.  If it is an Emacs bug, we hope someone can
1291 1292
explain what the bug is so we can fix it.  In the mean time, removing
the resource prevents the problem.
Dave Love's avatar
#  
Dave Love committed
1293

1294 1295 1296 1297 1298
*** FVWM: Some versions of FVWM incorrectly set the 'sticky' frame parameter.

Version 2.6.4 of the FVWM can make a frame sticky (appear on all user
desktops) when setting the 'sticky' frame parameter to nil.  This may
happen without any special user interaction, for example, when Emacs
1299
restores a saved desktop.  A fix is to install version 2.6.8 of FVWM,
1300 1301
see https://debbugs.gnu.org/cgi/bugreport.cgi?bug=31650.

1302
** General X problems
1303

1304
*** Redisplay using X is much slower than previous Emacs versions.
1305